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Printing History 

The manual printing date and part number indicate its current edition. The printing date changes 
when a new edition is printed. However, minor changes may be made at reprint without changing 
the printing date. The manual part number changes when extensive changes are made. 

To ensure that you receive new editions of this manual when changes occur, you may subscribe to 
the appropriate product support service, available through your HP sales representative. 

August 1992. Third Edition, This edition is an update to the Second Edition and is valid for 
HP~UX Release 9.0 on all HP 9000 systems. Replaces Second Edition, HP part number B2355- 
90004. 

June 1991. Second Edition. Update to the First Edition for HP-UX Release 8.05 on Series 700 
systems. Also valid for HP-UX Release 8.0 on Series 300/400 and Series 800 systems. Replaces 
First Edition, HP part number B 1864-90000. 

January 1991. First Edition. Replaces manual part number 09000-90013. Valid for HP-UX 
Release 8.0 on Series 300/400, 700, and Series 800 systems. The Networking Reference was 
merged into this manual at Release 8.0. 

New Features 

This edition contains several new features. 

Typography has been changed to conform to style used in other HP manuals as well as 
industry standards (conversion complete execpt for parts of Volume 3). Command names, 
argument names, and such appear on the printed page in exactly the same form as when they 
are typed in commands or applications, eliminating much confusion regarding capitalization of 
letters, which items are literals or otherwise, etc. 

Progressive bleed tabs in each section are positioned vertically on the page edge according to 
the first letter in the name of the manual entry for easier access. 

As part of an on-going effort to improve the quality and usability of this manual, several 
entries have been expanded and rewritten for better clarity and many examples have been 
added or expanded in many entries. Many changes are a direct result of comments, requests, 
and suggestions from users outside of HP. 

Manual is expanded considerably to conver new functionality from Open Software Foundation 
and several other sources as well as newer versions of NFS Services and other software 
contained in previous releases. 

Do You Have Comments or Suggestions? 

Comments and suggestions from users about this manual are always welcome because they 
are an important part of our on-going process of improving the HP-UX Reference. 

Internal HP users send electronic mail to: 

hpuxref @f c . hp . com 

Other users, please use the reply card provided in the manual or send a note or letter by 
ordinary mail to: 

HP-UX Reference Comments, MS 11 

Hewlett-Packard Company 

3404 East Harmony Road 

Fort Collins, CO 80525-9988, U.S.A. 
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Section 2: System Calls 

Entry Name(Section): name Description 

intro(2): introduction to system calls 

accept (2): accept ( ) accept connection on a socket 

access (2): access ( ) determine accessibility of a file 

acct(2): acct ( ) enable or disable process accounting 

alarm (2): alarm ( ) set a process's alarm clock 

atexit(2): atexit ( ) register a function to be called at program termination 

audctl(2): audctlf) start or halt auditing system: set or get audit files 

audswitch(2): audswitch( ) suspend or resume auditing on current process 

audwrite(2): audwrite ( ) write audit record for self-auditing process 

bind(2): bind ( ) .bind address to a socket 

brk(2): brk ( ) , sbrk ( ) change data segment space allocation 

bsdproc(2): killpg ( ) , getpgrp ( ) , setpgrp ( ) , sigvec ( ) , 

signal ( ) 4.2 BSD-compatible process control facilities 

chdir(2): chdir ( ) change working directory 

chmod(2): chmodO, fchmodO change access mode of file 

chown(2): chownO, fchownO change owner and group of a file 

chroot(2): chroot ( ) change root directory 

close(2): close ( ) .close a file descriptor 

cnodeid(2): cnodeidO get the cnode ID of the local machine 

cnodes(2): cnodes ( ) get a list of active nodes in cluster 

connect (2): connect ( ) initiate connection on a socket 

creat(2): creat ( ) create a new file or rewrite an existing one 

dup2(2): dup2 ( ) duplicate an open file descriptor to a specific slot 

dup(2): dup ( ) duplicate an open file descriptor 

errno(2): errnoO error indicator for system calls 

exec(2): execl ( ) , execv ( ) , execle ( ) , execve ( ) , execlp ( ) , execvp ( ) execute a file 

execle ( ) : execute a file see exec (2) 

execl ( ) : execute a file see exec(2) 

execlp ( ) : execute a file see exec (2) 

execve ( ) : execute a file see exec(2) 

execv ( ) : execute a file see exec (2) 

execvp ( ) : execute a file see exec (2) 

exit(2): exit ( ) , _exit ( ) .terminate process 

f chdir (2): change working directory see chdir(2) 

f chmod( ) : change access mode of file see chmod(2) 

f chown( ) : change owner and group of a file see chown(2) 

fcntl(2): fcntK) file control 

f getacl ( ) : get access control list (ACL) information see getacl(2) 

fork(2): fork ( ) .create a new process 

fpathconf ( ) : get configurable pathname variables see pathconf(2) 

fsctl(2): f sctl ( ) .file system control 

f setacl ( ) : set access control list (ACL) information see setacl(2) 

f statf s ( ) : get file system statistics see statfs(2) 

f stat ( ) : get file status see stat(2) 

f sync (2): f sync ( ) synchronize a file's in-core state with its state on disk 

ftime(2): f time ( ) get date and time more precisely 

f truncate ( ) : truncate a file to a specified length see truncate(2) 

getaccess(2): getaccess ( ) get a user's effective access rights to a file 

getacl (2): getacl ( ) , f getacl ( ) get access control list (ACL) information 

getaudid(2): getaudid( ) get the audit ID (aid ()) for the current process 

getaudproc(2): getaudproc ( ) get audit process flag for calling process 

getcontext(2): getcontext ( ) return the process context for context dependent file search 

getdirentries(2): getdirentries ( ) get entries from a directory in a filesystem-independent format 

getdomainname(2): getdomainname ( ) , setdomainname ( ) get/set name of current NIS domain 

getegid ( ) : get effective group ID see getuid(2) 

geteuid ( ) : get effective user group ID see getuid(2) 
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getevent(2): getevent ( ) get events and system calls currently being audited 

getfh(2): getfh() return file handle for file on remote node. 

getgid ( ) : get real group ID see getuid(2) 

getgroups(2): getgroups ( ) get group access list 

gethostname(2): gethostname ( ) get name of current host 

getitimer(2): getitimerO, setitimerO get/set value of interval timer 

getpeername(2): getpeername ( ) get address of connected peer 

getpgrp2: get process group ID of specified process see getpid(2) 

getpgrpO : 4.2 BSD-compatible process control facilities see bsdproc(2) 

getpgrp ( ) : get process group ID see getpid(2) 

getpid(2): getpid ( ) , getpgrp ( ) , getppid ( ) , getpgrp2 .... get process, process group, and parent process ID 

getppid ( ) : get parent process ID see getpid(2) 

getpriority(2): getpriority, setpriority get or set process priority 

getpriority: get process priority see getpriority(2) 

getrlimit(2): getrlimit ( ) , setrlimit ( ) control consumption of system resources 

getsockname(2): getsockname ( ) get socket address 

getsockopt(2): getsockopt ( ) , setsockopt ( ) get or set options on sockets 

gettimeofday(2): gettimeofdayO, settimeofdayO get/set date and time 

getuid(2): getuid ( ) , geteuid ( ) , getgid ( ) , 

getegid() get real user, effective user, real group, and effective group IDs 

gtty ( ) : control device see stty(2) 

ioctl(2): ioctlO control device 

ipcconnect(2): ipcconnect ()() request connection to another process 

ipccontrol(2): ipccontrol()() perform special operations onNetlPC sockets 

ipccreate(2): ipccreate ( ) () create a call socket 

ipcdest(2): ipcdest ( ) () create a destination descriptor 

ipcgetnodename(2): ipcgetnodename ( ) obtain NetlPC node name of current host 

ipclookup(2): ipclookup()() obtain a destination descriptor 

ipcname(2): ipcname ( ) () associate name with call socket or destination call socket 

ipcnamerase(2): ipcnamerase ( ) () delete name associated with a call socket or destination call socket 

ipcrecv(2): ipcrecv ( ) () establish or receive data on NetlPC virtual circuit connection 

ipcrecvcn(2): ipcrecvcn( ) () receive connection request on a call socket 

ipcselect(2): ipcselect ()() determine status of call socket or VC socket 

ipcsend(2): ipcsend()() send data on a virtual circuit connection 

ipcsetnodename(2): ipcsetnodename ( ) set NetlPC node name of host CPU 

ipcshutdown(2): ipcshutdown()() release a descriptor 

kill(2): kill ( ) , raise ( ) send a signal to a process or a group of processes 

killpgO: 4.2 BSD-compatible process control facilities see bsdproc(2) 

link(2): link() fink to a file 

listen (2): listen ( ) listen for connections on a socket 

lockf(2): lockf ( ) provide semaphores and record locking on files 

lseek(2): lseek ( ) move read/write file pointer; seek 

lstat ( ) : get file status see stat(2) 

lsync ( ) : update super-block see sync(2) 

madvise(2): madvise advise system of process' expected paging behavior 

mkdir(2): mkdir ( ) .make a directory file 

mknod(2): mknod() make a directory, or a special or ordinary file 

mkrnod( ) - make a cnode-specific special file see mknod(2) 

mmap(2): mmap map object into virtual memory 

mount (2): mount ( ) mount a file system 

mprotect(2): mprotect modify memory mapping access protections 

msem_init(2): msem_init initialize semaphore in mapped file or anonymous memory region 

msem_lock(2): msem_lock lock a semaphore 

msem_remove(2): msem_remove remove semaphore in mapped file or anonymous region 

msem_unlock(2): msem_unlock unlock a semaphore 

msgget(2): msgget ( ) .get message queue 

msgop(2): msgsndO, msgrcvO message operations 
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msgrcvO : message operations see msgop(2) 

mstctl(2): msgctl ( ) message control operations 

msync(2): msync synchronize a mapped file 

munmap(2): munmap .unmap a mapped region 

nfssvc(2): nf ssvc ( ) , async_daemon NFS daemons 

nice(2): nice() change priority of a process 

open (2): open ( ) open file for reading or writing 

pathconf(2): pathconf (), fpathconf () get configurable pathname variables 

pause(2): pause ( ) suspend process until signal 

pipe (2): pipe ( ) create an interprocess channel 

plock(2): plock ( ) lock process, text, or data in memory 

poll (2): poll - monitor I/O conditions on multiple file descriptors 

prealloc(2): prealloc ( ) preallocate fast disk storage 

profil(2): prof il ( ) execution time profile 

ptrace(2): ptraceO .process trace 

quotactl(2): quotactl ( ) manipulate disk quotas 

raise ( ) - send a signal to a process or a group of processes see kill (2) 

read(2): read(), readv() j-ead input 

readlink(2): readlink() read value of a symbolic link 

readv ( ) : read input .seeread(2) 

reboot (2): reboot ( ) boot the system 

recv(2): recv(), recvfromO recvmsgO receive message from a socket 

recvf rom( ) : receive message from a socket see recv(2) 

recvmsg ( ) : receive message from a socket see recv(2) 

rename(2): rename ( ) change the name of a file 

rmdir(2): rmdir ( ) .remove a directory file 

rtprio(2): rtprio ( ) change or read real-time priority 

sbrk ( ) : change data segment space allocation see brk(2) 

select (2): select ( ) synchronous I/O multiplexing 

semctl(2): semctl ( ) semaphore control operations 

semget(2): semget ( ) .get set of semaphores 

semop(2): semop ( ) semaphore operations 

send(2): send(), sendtoO send message to a socket 

sendmsg ( ) : send message to a socket see send(2) 

sendto ( ) : send message to a socket see send(2) 

setacl(2): setacl ( ) , f setacl ( ) set access control fist (ACL) information 

setaudid(2): setaudidO set audit ID (aid()) for current process 

setaudproc(2): setaudproc ( ) set or clear auditing on calling process 

setevent(2): setevent ( ) set current events and system calls to be audited 

setgidO: set group ID seesetuid(2) 

setgroups(2): setgroups ( ) set group access Ust 

sethostname(2): sethostname ( ) set name of host cpu 

setitimerO: set value of interval timer see getitimer(2) 

setpgid(2): setpgid(), setpgrp2 set process group ID for job control 

setpgrp2: set process group ID see setpgid(2) 

setpgrpO : 4.2 BSD-compatible process control facilities see bsdproc(2) 

setpgrp ( ) - create session and set process group ID see setsid(2) 

setpriority: set process priority see getpriority(2) 

setresgid(): set real, effective, and saved group IDs see setresuid(2) 

setresuid(2): setresuid( ) , setresgid( ) set real, effective, and saved user and group IDs 

setrlimit () - control consumption of system resources see getrlimit(2) 

setsid(2): setsid ( ) , setpgrp ( ) create session and set process group ID 

setsockopt ( ) : set options on sockets see getsockopt(2) 

settimeofdayO: set date and time see gettimeofday(2) 

setuid(2): setuidO, setgidO set user and group IDs 

shmctl(2): shmctl ( ) shared memory control operations 

shmdt ( ) : shared memory operations see shmop(2) 
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Entry Name(Section): name Description 

shmget(2): shmget ( ) .get shared memory segment 

shmop(2): shmat ( ) , shmdt ( ) shared memory operations 

shut down (2): shutdown () shut down a socket 

sigaction(2): sigaction() examine and change signal action 

sigblock(2): sigblock ( ) hlock signals 

sighold ( ) : signal management see sigset(2V) 

sigignore ( ) : signal management see sigset(2V) 

signal (2): signal () specify what to do upon receipt of a signal 

signal ( ) : 4.2 BSD-compatible process control facilities see bsdproc(2) 

sigpause(2): sigpause ( ) atomically release blocked signals and wait for interrupt 

sigpause ( ) : signal management see sigset(2V) 

sigpending(2): sigpending ( ) examine pending signals 

sigprocmask(2): sigprocmaskt ) examine and change blocked signals 

sigrelse ( ) : signal management see sigset(2V) 

sigset(2V): sigset ( ) , sighold ( ) , sigrelse ( ) , sigignore ( ) , sigpause ( ) signal management 

sigsetmask(2): sigsetmask ( ) set current signal mask 

sigspace(2): sigspace ( ) assure sufficient signal stack space 

sigstack(2): sigstackO set and/or get signal stack context 

sigsuspend(2): sigsuspend( ) wait for a signal 

sigvec ( ) : 4.2 BSD-compatible process control facilities see bsdproc(2) 

sigvector(2): sigvector ( ) software signal facilities 

socket(2): socket ( ) create an endpoint for communication 

socketpair(2): socketpair ( ) create a pair of connected sockets 

stat(2): stat ( ) , lstat ( ) , f stat ( ) get file status 

statfs(2): statf s ( ) , f statf s ( ) get file system statistics 

stime(2): stime ( ) .set time and date 

stty(2): stty(),gtty() .control device 

swapon(2): swaponO add a swap device for interleaved paging/swapping 

symlink(2): symlink ( ) make symbolic link to a file 

sync(2): sync ( ) , lsync ( ) .update super-block 

sysconf(2): sysconf get configurable system variables 

time(2): time() get time 

times(2): times ( ) get process and child process times 

truncate(2): truncate ( ) , f truncate ( ) truncate a file to a specified length 

ulimit(2): ulimit ( ) .get and set user limits 

umask(2): umask ( ) set and get file creation mask 

umount(2): umount ( ) .unmount a file system 

uname(2): uname ( ) get name of current HP-UX system 

unlink (2): unlink remove directory entry; delete file 

ustat(2): ustat ( ) .get file system statistics 

utime(2): utime ( ) set file access and modification times 

vfork(2): vf ork ( ) spawn new process (use fork ( ) intead) 

vfsmount(2): vf smount ( ) .mount a file system 

wait (2): wait ( ) , wait3 ( ) wait for child or traced process to stop or terminate 

wait 3 ( ) : wait for child or traced process to stop or terminate see wait(2) 

waitpid ( ) : wait for child or traced process to stop or terminate see wait(2) 

write(2): writeO, writevO write on a file 

writev ( ) : write on a file see write(2) 
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Section 3: Library Routines 

Entry Name(Section): name Description 

a64l(3C): a641 ( ) , 164a ( ) convert between long integer and base-64 ASCII string 

intro(3): Intro ( ) introduction to subroutines and libraries 

AAudioString(3X): AAudioString ( ) get name of audio controller (string) passed to AOpenAudioO 

ABestAudioAttributes(3X): ABestAudioAttributes ( ) get best audio attributes for specified controller 

abort (3C): abort ( ) generate a software abort fault 

abs(3C): abs ( ) , abs ( ) return integer absolute value 

ACalculateLength(SX): ACalculateLengthO return the size in bytes of converted data 

ACheckEvent(3X): ACheckBvent ( ) get first event found in audio event queue 

ACheckMaskEvent(3X): ACheckMaskEvent ( ) get first event in audio event queue that matches mask 

AChooseAFileAttributes(3X): AChooseAPileAttributes ( ) select attributes for creating new file 

AChoosePlayAttributes(3X): AChoosePlayAttributes ( ) select attributes for playing file or stream 

AChooseSourceAttributes(3X): select attributes associated with existing file or stream 

aclentrystart ( ) : convert pattern string form to access control fist (ACL) structure see strtoacl(3C) 

ACloseAudio(3X):ACloseAudio() close connection to specific audio server 

acltostr(3C): acltostr ( ) convert access control list (ACL) structure to string form 

AConnectionNumber(3X): AConnectionNuiriber ( ) get audio server connection number 

AConnectRecordStream(3X):AConnectRecordStream( ) connect socket to TCP socket address 

AConvertAFile(3X): AConvertAFile ( ) convert audio file data format 

AConvertBuffer(3X): AConvertBufferO convert a buffer of data 

acosdf ( ) : trigonometric arccosine function (float, degrees) see trigd(3M) 

acosd( ) : trigonometric arccosine function (degrees) see trigd(3M) 

acosf ( ) : trigonometric arccosine function (float) see trig(3M) 

acosh ( ) : inverse hyperbolic cosine function see sinh(3M) 

acos ( ) : trigonometric arccosine function see trig(3M) 

ACreateSBucket(3X): ACreateSBucket ( ) create empty sound bucket and return pointer to it 

ADataFormats(3X): ADataFormat s ( ) get fist of data formats supported by audio controller 

addexportent ( ) -access exported file system information see exportent(3N) 

addmntent ( ) : get file system descriptor file entry see getmntent(3X) 

addopt(3N): addopt ( ) add argument and data to NetlPC option buffer 

ADestroySBucket(3X): ADestroySBucket ( ) destroy specified sound bucket 

advance o: process 16-bit characters see nl_tools_16(3C) 

advance ( ) : regular expression compile and match routines see regexp(3X) 

AEndConversion(3X): AEndConversionO finish stream data conversion 

AEventsQueued(3X): AEventsQueued ( ) get number of events in queue for specified server connection 

AGetAFileAttributes(3X): AGetAPileAttributes ( ) get file attributes of specified file 

AGetASilenceValue(3X): AGetSilenceValue ( ) get a silence value 

AGetChannelGain(3X): AGetChannelGain get transaction channel gain 

AGetDataFormats(3X): AGetDataFormats ( ) get data formats for a specified file format 

AGetErrorText(3X):AGetErrorText ( ) copy error description into specified buffer 

AGetGain(3X):AGetGain ( ) get play volume or record gain of specified transaction 

AGetSBucketData(3X): AGetSBucketData t*py audio data in sound bucket to buffer; return number of bytes 

AGetSystemChannelGain(3X): AGetSystemChannelGain ( ) get system or monitor channel gain 

AGetTransStatus(3X):AGetTransStatus ( ) get status of specified transaction 

AGMGainRestricted(3X):AGMGainRestricted ( ) find out if audio controller restricts gain entries 

AGrabServer(3X): AGrabServer ( ) acquire exclusive use of audio server 

AInputChannels(3X):AInputChannels ( ) get list of A/D input channels on current hardware 

AInputSources(3X):AInputSources ( ) get types of input sources existing on current hardware 

almanac (3X): almanac ( ) return numeric date information in MPE format 

ALoadAFile(3X):ALoadAFile ( ) copy audio file into new sound bucket with data conversion 

alphasort () - sort a directory pointer array see scandir(3C) 

AMaskEvent(3X):AMaskEvent ( ) get first matching event in audio event queue 

AMaxInputGain(3X):AMaxlnputGain ( ) get maximum input gain supported by audio controller 

AMaxOutputGain(3X) :AMaxOut put Gain ( ) get maximum output gain supported by audio controller 

AMinInputGain(3X):AMinInputGain ( ) get minimum input gain supported by audio controller 

AMinOutputGain(3X):AMinOutputGaln ( ) get minimum output gain supported by audio controller 
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Entry Name(Section): name Description 

ANextEvent(3X):ANextEvent ( ) dequeue and return first event in audio event queue 

ANumDataFormats(3X): ANumDataFonrtats ( ) data formats, number supported by audio controller 

ANumSamplingRates(3X): ANumSamplingRates ( ) number of sampling rates supported by audio controller 

AOpenAudio(3X):AOpenAudio() open connection to specified audio server 

AOutputChannels(3X):AOutputChannels ( ) get D/A output channels existing on current hardware 

AOutputDestinations(3X) : AOutput De s t inat ions ( ) output destinations types on current hardware 

APauseAudio(3X): APause Audio ( ) pause the specified audio transaction 

APeekEvent(3X): APeekEvent ( ) return but do not dequeue first event in audio event queue 

APlaySBucket(3X): APlaySBucket ( ) play specified sound bucket and return transaction ID 

APlaySStream(3X):APlaySStream( ) initiate transaction and return transaction ID and SStream structure 

AProtocolRevision(3X):AProtocolRevision ( ) .... get minor revision number of protocol used by audio server 

AProtocolVersion(3X) : AProtocolVersion ( ) get major version number of protocol used by audio server 

APutBackEvent(3X): APutBackEvent ( ) ....push event onto head of audio event queue 

APutSBucketData(3X): APutSBucketData ( ) copy audio data from buffer to sound bucket 

AQLength(3X): AQLength( ) return number of events on audio event queue 

AQueryAFile(3X)AQueryAFile() get file format of specified file 

ARecordAData(3X): ARecordAData ( ) read audio data into sound bucket 

ARecordSStream(3X):ARecordSStream( ) . initiate transaction; return transaction ID and SStreams structure 

AResumeAudio(3X): AResumeAudio ( ) resume specified audio transaction 

ASamplingRates(3X):ASamplingRates ( ) return list of sampling rates supported by audio controller 

ASaveSBucket(3X):ASaveSBucket ( ) write sound bucket data into file with data conversion 

asctime ( ) : convert date and time to string see ctime(3C) 

ASelectInput(3X):ASelectInput ( ) request report of specified audio events 

AServerVendor(3X): AServerVendor ( ) get vendor name of audio server for this connection 

ASetChannelGain(3X): ASetChannelGainO set transaction channel gain 

ASetCloseDownMode(3X): .. set close-down mode to destroy or complete transactions on specified connection 

ASetErrorHandler(3X): ASetErrorHandler ( ) replace default error handler with specified handler 

ASetGain(3X) ASetGain( ) set play volume or record gain of specified transaction 

ASetIOErrorHandler(3X): ASetlOErrorHandler ( ) replace default I/O error handler with specified handler 

ASetSystemChannelGain(3X): ASetSystemChannelGain ( ) set system or monitor channel gain 

ASetSystemPlayGain(3X):ASetSystemPlayGain( ) set system play volume 

ASetSystemRecordGain(3X):ASetSystemRecordGain( ) set system record gain 

ASetupConversion(3X): ASetupConversion ( ) perform setup required for stream data conversion 

ASimplePlayer(3X):ASimplePlayer ( ) return gain matrix of basic play device 

ASimpleRecorder(3X):ASimpleRecorder ( ) return gain matrix of basic recording device 

asindf ( ) : trigonometric arcsine function (float, degrees) see trigd(3M) 

asind(): trigonometric arcsine function (degrees) seetrigd(3M) 

asinf ( ) : trigonometric arcsine function (float) see trig(3M) 

asinh(3M): asinh.(), acosh(), atanh() inverse hyperbolic functions 

asin(): trigonometric arcsine function see trig(3M) 

ASoundBitOrder(3X): ASoundBitOrder ( ) get bit order used for one-bit-per-sample data 

ASoundByteOrder(3X): get byte order of audio data accepted by audio controller for this connection 

assert (3X): assert ( ) .verify program assertion 

AStopAudio(3X): AStopAudio( ) stop specified audio transaction 

AtAddCallback(3X):AtAddCallback() add callback procedure for the toolkit 

atan2df ( ) : trigonometric arctangent-and-quadrant function (float, degrees) see trigd(3M) 

atan2d( ) : trigonometric arctangent-and-quadrant function (degrees) see trigd(3M) 

atan2£ ( ) : trigonometric arctangent-and-quadrant function (float) see trig(3M) 

atan2 ( ) : trigonometric arctangent-and-quadrant function see trig(3M) 

atandf ( ) : trigonometric arctangent function (float, degrees) see trigd(3M) 

atand( ) : trigonometric arctangent function (degrees) see trigd(3M) 

atanf ( ) : trigonometric arctangent function (float) see trig(3M) 

atanh( ) : inverse hyperbolic tangent function see sinh(3M) 

atari ( ) : trigonometric arctangent function see trig(3M) 

AtInitialize(3X) Atlnitialize ( ) add audio event handler for this connection 

atof () : convert string to double-precision number see strtod(3C) 

AtRemoveCallback(3X): AtRemoveCallback ( ) set callback to NULL 

x Table of Contents: Volume 2 



Table of Contents 
Volume 2 

Entry Name(Section): name Description 

AuCreatePlay(3X): AuCreatePlayO create an audio play widget 

AuCreateRecord(3X): AuCreateRecord( ) create an audio record widget 

AuInvokePlay(3X): AuInvokePlay O initiate a widget play operation 

AuInvokeRecord(SX): AulnvokeRecord ( ) initiate an audio widget record operation 

AUngrabServer(3X): AUngrabServer ( ) release server from exclusive use by this connection 

AUpdateDataLength(3X): AUpdateDataLengthO update a file's header 

AuPlayWidget(SX): AuPlayWidget ( ) audio play widget 

AuRecordWidget(3X): AuRecordWidget ( ) audio record widget 

AuSaveFile(3X): AuSaveFile ( ) save sound bucket data created by record widget 

AVendorRelease(3X): AVendorRelease ( ) get vendor release number of audio server for this connection 

AWriteAHeader(3X): AWriteAHeader ( ) write a header for an audio file 

bcmp ( ) : memory operations ..see memory(3C) 

bcopy( ) : memory operations see memory(3C) 

bessel(3M): j ( ) , j 1 ( ) , jn( ) , yO ( ) , yl ( ) , yn( ) Bessel functions 

bindresvport(3N): bindresvport ( ) bind a socket to a privileged IP port 

blclose( ) - terminal block-mode library interface see blmode(3C) 

blget ( ) - terminal block-mode library interface see blmode(3C) 

blmode(3C): blmode ( ) terminal block-mode library interface 

blopen( ) -terminal block-mode library interface see blmode(3C) 

blread( ) - terminal block-mode library interface see blmode(3C) 

blset ( ) -terminal block-mode library interface see blmode(3C) 

bsearch(3C): bsearch( ) binary search a sorted table 

byteorder(3N): htonl ( ) , htons ( ) , ntohl ( ) , ntohs ( ) .. convert values between host and network byte order 

byte_status ( ) , byte_statos ( ) : process 16-bit characters see nl_tools_16(3C) 

bzero ( ) : memory operations see memory(3C) 

cabs ( ) - complex absolute value function see hypot(3M) 

cachectl(3C): cachectl ( ) flush and/or purge the cache 

calendar(3X): calendar ( ) return the MPE calendar date 

calloc: main memory allocator see malloc(3C) 

catclose ( ) : close NLS message catalog for reading see catopen(3C) 

catgetmsg(3C): catgetmsg ( ) get message from a message catalog 

catgets(3C): catgets ( ) get a program message 

catopen(3C): catopen( ) , catclose ( ) open or close NLS message catalog for reading 

catread(3C): catreadO MPE/RTE-style message catalog support 

cbrt ( ) : cube root function see exp(3M) 

cbrtf ( ) : cube root function (float version) see exp(3M) 

c_colwidth ( ) , c_colwidth() : process 16-bit characters see nl_tools_16(3C) 

ceil ( ) : ceiling function see floor(3M) 

cfgetispeedO: get tty intput baud rate see cfspeed(3C) 

cf getospeed ( ) : get tty output baud rate see cfspeed(3C) 

cf setispeed(): set tty intput baud rate see cfspeed(3C) 

cf setospeed ( ) : set tty output baud rate see cfspeed(3C) 

cfspeed(3C): cfgetospeed(), cfsetospeedO, cfgetispeedO, cfsetispeedO ...tty baud rate functions 

charadvo : process 16-bit characters see nl_tools_16(3C) 

charato: process 16-bit characters see nl_tools_16(3C) 

chownacl(3C): chownacl ( ) change owner and/or group in access control list (ACL) 

clearenv(3C): clearenv clear the process environment 

clearerr: stream status inquiries see ferror(3S) 

clock(3C): clock ( ) report CPU time used 

clock (3X): clock () return the MPE clock value 

closedir ( ) : directory operations see directory(3C) 

closelog ( ) : control system log see syslog(3C) 

compile ( ) : regular expression compile and match routines see regexp(3X) 

confstr(3C): confstrO get string-valued configuration values 

conv(3C): toupper ( ) , tolower ( ) , _toupper, _tolower, toascii ( ) translate characters 

copysignO, copysignf (): copysign manipulations see ieee(3M) 

copysignf (), copysignO: copysign manipulations seeieee(3M) 
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cosdf ( ) : trigonometric cosine function (float, degrees) see trigd(3M) 

cosd(): trigonometric cosine function (degrees) seetrigd(3M) 

cosf ( ) : trigonometric cosine function (float) see trig(3M) 

coshf ( ) : hyperbolic cosine function (float version) see sinh(3M) 

cosh(): hyperbolic cosine function seesinh(3M) 

cos ( ) : trigonometric cosine function see trig(3M) 

cpacl(3C): cpacl ( ) , fcpacl ( ) copy access control list (ACL) to another file 

crt0(3): crtO.o, mcrtO.o, frtO.o, mfrtO.o execution startup routines 

crtO . o: execution startup routines see crt0(3) 

crypt(3C): crypto, setkeyO, encrypt () generate hashing encryption 

etermid(3S): ctermidO generate file name for terminal 

ctime(3C): ctime ( ) , nl_cxtime ( ) , localtime ( ) , gmtime ( ) , asctime ( ) , nl_ascxtime ( ) , timezone ( ) , 

daylight ( ) , tzname ( ) , tzset ( ) , nl_ctime ( ) , nl_asctime ( ) convert date and time to string 

ctime ( ) : convert date and time to string see ctime(3C) 

ctype(3C): , isalpha ( ) , isupper ( ) , islower ( ) , isdigit ( ) , isxdigit ( ) , isalnum( ) , isspace ( ) , 

ispunctO, isprintO, isgraphO, iscntrlO, isasciiO classify characters 

currlangid( ) : NLS information about native languages see langinfo(3C) 

curses(3X): curses ( ) CRT screen handling and optimization package 

cuserid(3S): cuserid ( ) get character login name of the user 

cvtnum(3C): cvtnumO convert string to floating point number 

datalock(3C): datalock ( ) lock process into memory after allocating data and stack space 

daylight ( ) : convert date and time to string see ctime(3C) 

dbm(3X): dbminit ( ) , fetch ( ) , store ( ) , delete ( ) , f irstkey ( ) , 

nextkey ( ) , dbmclose ( ) database subroutines 

dbm_clearerr: database subroutines see ndbm(3X) 

dbmclose ( ) : database subroutines see dbm(3X) 

dbm_close: database subroutines see ndbm(3X) 

dbm_delete: database subroutines see ndbm(3X) 

dbm_error: database subroutines see ndbm(3X) 

dbm_fetch: database subroutines .see ndbm(3X) 

dbm_f irstkey: database subroutines see ndbm(3X) 

dbminit ( ) : database subroutines see dbm(3X) 

dbm_nextkey: database subroutines see ndbm(3X) 

dbm_open: database subroutines see ndbm(3X) 

dbm_store: database subroutines see ndbm(3X) 

delete ( ) : database subroutines see dbm(3X) 

devnm(3): devnm( ) map device ID to file path 

dial(3C): dial ( ) , undial ( ) establish an out-going terminal line connection 

dif f time ( ) : difference between calendar times see ctime(3C) 

directory(3C) : opendir ( ) , readdir ( ) , 

telldir ( ) , seekdir ( ) , rewinddir ( ) , closedir ( ) directory operations 

div(3C): div(), ldiv() integer division and remainder 

dn_comp, dn_expand, - resolver routines see resolver(3N) 

drand48(3C): drand48 ( ) , erand48 ( ) , lrand48 ( ) , nrand48 ( ) , mrand48 ( ) , j rand48 ( ) , srand48 ( ) , 

seed48 ( ) , lcong48 ( ) generate uniformly distributed pseudo-random numbers 

drem( ) : remainder manipulations see ieee(3M) 

ecvt(3C): ecvt ( ) , f cvt ( ) , gcvt ( ) , nl_gcvt ( ) convert floating-point number to string 

edata: last locations in program see end(3C) 

encrypt ( ) : generate hashing encryption see crypt(3C) 

end(3C): end, etext, edata last locations in program 

endccent ( ) : get cluster configuration entry see getccent(3C) 

endexportent ( ) - access exported file system information see exportent(3N) 

endf sent ( ) : get file system descriptor file entry see getfsent(3X) 

endgrent ( ) : get group file entry see getgrent(3C) 

endhostent ( ) : get network host entry see gethostent(3N) 

endmntent ( ) : get file system descriptor file entry see getmntent(3X) 

endnetent ( ) : get network entry see getnetent(3N) 
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endprotoent ( ) : get protocol entry see getprotoent(SN) 

endpwent ( ) : get password file entry see getpwent(3C) 

endpwent ( ) : get secure password file entry see getspwent(3C) 

endservent ( ) : get service entry see getservent(3N) 

endusershell ( ) - close legal user shells file see getusershell(SC) 

endutent ( ) : access utmp file entry see getut(3C) 

erand48 ( ) : generate pseudo-random numbers see drand48(3C) 

erf(3M): erf ( ) , erf c ( ) error function and complementary error function 

erf c ( ) : error function and complementary error function see erf(3M) 

errno: system error messages see perror(3C) 

error_$intro(3): error_$intro error text database operations 

error_$c_get_text(3): error_$c_get_text ( ) return subsystem, module, and error texts for a status code 

error_$c_text(3): error_$c_text ( ) return an error message for a status code 

etext: last locations in program see end(3C) 

exp(3M): exp ( ) , log ( ) , loglO ( ) , log2 ( ) , pow ( ) , sqrt ( ) , cbrt ( ) , expf ( ) , logf ( ) , 

loglOf ( ) , log2f ( ) , powf ( ) , sqrtf ( ) ... exponential, logarithm, power, square root, cube root functions 

expf ( ) : exponential function (float version) see exp(3M) 

exportent(3N): export ent ( ) , getexportent ( ) , setexportent ( ) , addexportent ( ) , remexportent ( ) , 

endexportent ( ), getexportopt ( ) access exported file system information 

f abs ( ) : absolute value function see floor(3M) 

f absf ( ) : absolute value function (float version) see floor(3M) 

fclose(3S): f close ( ) , f f lush( ) close or flush a stream 

f cpacl ( ) : copy access control list (ACL) to another file see cpacl(3C) 

f cvt ( ) : convert floating-point number to string see ecvt(3C) 

f dopen( ) : associate a stream with a file descriptor see fopen(3S) 

f eof : stream status inquiries see ferror(3S) 

ferror(3S): f error, f eof , clearerr, f ileno stream status inquiries 

f etch( ) : database subroutines see dbm(3X) 

f flush ( ) : flush a stream see fclose(3S) 

f f s ( ) : memory operations see memory(3C) 

f get c cent ( ) : get cluster configuration entry see getccent(3C) 

f getc ( ) : get character from a stream file see getc(3S) 

f getgrent ( ) : get group file entry see getgrent(3C) 

fgetpos(3S): f getpos ( ) , f setpos ( ) save or restore file position indicator for a stream 

f getpwent ( ) : get password file entry see getpwent(3C) 

f getpwent ( ) : get secure password file entry see getspwent(3C) 

f gets ( ) : get a string from a stream see gets(3S) 

f getwc ( ) : get wide character from a stream file see getwc(3C) 

f getws ( ) : get a wide string from a stream see getws(3C) 

fileno(3S): f ileno ( ) map stream pointer to file descriptor 

f initef ( ) , finite ( ) : floating-point classification functions see ieee(3M) 

finite ( ) , f initef ( ) : floating-point classification functions see ieee(3M) 

firstkeyO : database subroutines see dbm(3X) 

f irstof 4 ( ) , PiRSTof 2 ( ) : process 16-bit characters see nl_tools_16(3C) 

floor (3M): floor ( ) , ceil ( ) , f mod ( ) , f abs ( ) , 

f absf ( ) , rint ( ) floor, ceiling, remainder, absolute value functions 

fmodf ( ) : remainder function (float version) see floor(3M) 

fmod(): remainder function .see floor(3M) 

fnmatch(3C): fnmatchO match filename patterns 

fopen(3S): f open( ) , f reopen ( ) , f dopen( ) open or re-open a stream file; convert file to stream 

fpclassify(3M): fpclassify ( ) , fpclassifyf ( ) floating-point classification functions 

f pclassif yf ( ) : floating-point classification function (float version) see fpclassify(3M) 

f pgetcontrol ( ) , f psetcontrol ( ) : floating-point control register functions see fpgetround(3M) 

f pgetf astmode ( ) , f psetf astmode ( ) : floating-point underflow mode functions see fpgetround(3M) 

f pgetmask ( ) , f psetmask ( ) : floating-point exception trap enables functions see fpgetround(3M) 

fpgetround(3M): fpget round ( ) , f pset round ( ) , f pgetmask ( ) , f psetmask ( ) , fpget sticky ( ) , 

f psetsticky ( ) , f pgetcontrol ( ) , f psetcontrol ( ) , f pgetf astmode ( ) , 
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f psetf astmode ( ) , fpsetdef aults ( ) floating-point mode control functions 

fpgetsticky ( ) , fpsetsticky ( ) : floating-point exception flags functions see fpgetround(3M) 

fprintf ( ) : print formatted output see printf(3S) 

f printmsg ( ) : print formatted output with numbered arguments see printmsg(3C) 

fpsetcontrol ( ) , f pgetcontrol ( ) : floating-point control register functions see fpgetround(3M) 

fpsetdef aults ( ) : floating-point control register defaults functions see fpgetround(3M) 

f psetf astmode ( ) , fpgetf astmode ( ) : floating-point underflow mode functions see fpgetround(3M) 

fpsetmask ( ) , f pgetmask ( ) : floating-point exception trap enables functions see fpgetround(3M) 

fpsetround( ) , fpgetround( ) : floating-point rounding mode functions see fpgetround(3M) 

fpsetstickyO, fpgetsticky(): floating-point exception flags functions see fpgetround(3M) 

fputc ( ) : put character on a stream see putc(3S) 

f puts ( ) : put a string on a stream see puts(3S) 

f putwc ( ) : put wide character on a stream see putwc(3C) 

fputws ( ) : put a wide string on a stream see putws(3C) 

fread(3S): fread(), fwrite() buffered binary input/output to a stream file 

free: main memory allocator .see malloc(3C) 

f reopen ( ) : re-open a stream file; convert file to stream see fopen(3S) 

frexp(3C): f rexp, ldexp, modf split floating-point into mantissa and exponent 

f rtO .o: execution startup routines see crt0(3) 

f scanf ( ) : formatted input conversion, read from stream file see scanf(3S) 

fseek(3S): f seek, rewind, f tell reposition a file pointer in a stream 

fsetaclentryO : add, modify, or delete access control list entry see setaclentry(3C) 

f setpos ( ) - restore file position indicator for a stream see fgetpos(3S) 

f statf sdev(): get file system statistics see statfsdev(3C) 

f tell: reposition a file pointer in a stream see fseek(3S) 

f tok ( ) - standard interprocess communication package see stdipc(3C) 

ftw(3C): f tw, f twh .walk a file tree 

f twh: walk a file tree .see ftw(3C) 

fwrite(): buffered binary output to a stream file seefread(3S) 

gamma (3M): gammaO, IgammaO, signgamO log gamma function 

gcrtO .o: execution startup routines see crt0(3) 

govt ( ) : convert floating-point number to string see ecvt(3C) 

getc(3S): getc ( ) , getchar ( ) , f getc ( ) , getw( ) get character or word from a stream file 

getcccidO: get cluster configuration entry see getccent(3C) 

getccent(3C): getccent ( ) , getcccid ( ) , getccnam( ) , setccent ( ) , 

endccent ( ) , f getccent ( ) get cluster configuration entry 

getccnamO : get cluster configuration entry see getccent(3C) 

getcdf(3C): getcdf ( ) , hidecdf ( ) manipulate CDF path names 

getchar ( ) : get character from a stream file see getc(3S) 

getclock(3C): getclock get current value of system-wide clock 

getcwd(3C): getcwd( ) , gethcwd( ) get path-name of current working directory 

getdate(3C): getdate ( ) convert user format date and time 

getdiskbyname(3C) :getdiskbyname ( ) get disk description by its name 

getenv(3C): getenvO return value for environment name 

getexportent ( ) - access exported file system information see exportent(3N) 

getexportopt ( ) - access exported file system information see exportent(3N) 

getf sent (3X): get f sent ( ) , getf sspec ( ) , getf sf ile ( ) , getf stype ( ) , 

setf sent ( ) , endf sent ( ) get file system descriptor file entry 

getf sent ( ) : get file system descriptor file entry see getfsent(3X) 

getf sf ile ( ) : get file system descriptor file entry see getfsent(3X) 

getf sspec ( ) : get file system descriptor file entry see getfsent(3X) 

getf stype ( ) : get file system descriptor file entry see getfsent(3X) 

getgrent(3C) : getgrent ( ) , getgrgid ( ) , getgrnam ( ) , setgrent ( ) , 

endgrent ( ) , f getgrent ( ) get group file entry 

getgrgidO, getgrnam(): get group file entry see getgrent(3C) 

gethcwd( ) : get path-name of current working directory see getcwd(3C) 

gethostbyaddr ( ) : get network host entry see gethostent(3N) 
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gethostbyname ( ) : get network host entry see gethostent(SN) 

gethostent(3N): gethostent ( ) , gethostbyaddr ( ) , gethostbyname ( ) , 

sethostent ( ) , endhostent ( ) get network host entry 

gethostent ( ) : get network host entry see gethostent(SN) 

getlocale ( ) : get the locale of a program see setlocale(3C) 

getlogin(3C): getlogin( ) .get login name 

getmntent(3X): getmntent ( ) , setmntent ( ) , addmntent ( ) , 

endmntent ( ) , hasmntopt ( ) get file system descriptor file entry 

getnetbyaddr ( ) : get network entry see getnetent(3N) 

getnetbyname ( ) : get network entry see getnetent(SN) 

getnetent(3N): getnetent ( ) , getnetbyaddr ( ) , getnetbyname ( ) , 

setnetent ( ) , endnetent ( ) get network entry 

getnetent ( ) : get network entry see getnetent(3N) 

getnetgrent(3C): getnetgrent ( ) , setnetgrent ( ) , endnetgrent ( ) , innetgr ( ) get network group entry 

getopt(3C): getopt ( ) , optarg, optind, opterr get option letter from argument vector 

getpass(3C): getpass ( ) .read a password 

getprotobyname ( ) : get protocol entry see getprotoent(3N) 

getprotobynumber ( ) : get protocol entry see getprotoent(3N) 

getprotoent(3N): getprotoent ( ) , getprotobynumber ( ) , getprotobyname ( ) , 

setprotoent ( ) , endprotoent ( ) get protocol entry 

getprotoent ( ) : get protocol entry see getprotoent(3N) 

getpw(3C): getpw() .get name from UID 

getpwent(3C): getpwent ( ) , getpwuid ( ) , getpwnam ( ) , setpwent ( ) , 

endpwent ( ) , f getpwent ( ) get password file entry 

getpwent ( ) : get password file entry see getpwent(3C) 

getpwent ( ) : get secure password file entry see getspwent(3C) 

getrpcent(3C): getrpcent (), getrpcbyname ( ) , getrpcbynumber ( ) get rpc entry 

getrpcport(3N): getrpcport ( ) get RPC port number 

gets(3S): gets ( ) , f gets ( ) get a string from a stream 

getservbyname ( ) : get service entry see getservent(3N) 

getservbyport ( ) : get service entry see getservent(3N) 

getservent(3N): get servant ( ) , getservbyport ( ) , getservbyname ( ) , 

setservent ( ) , endservent ( ) get service entry 

getservent ( ) : get service entry see getservent(3N) 

getspwaid( ) : get secure password file entry see getspwent(3C) 

getspwent(3C): getpwent ( ) , getpwuid ( ) , getpwnam( ) , setpwent ( ) , 

endpwent ( ) , f getpwent ( ) get secure password file entry 

getsubopt(3C): getsubopt ( ) parse suboptions from a string. 

gettimer(3C): gettimer get value of a per-process timer 

getusershell(3C): getusershell ( ) , setusershell ( ) , endusershell ( ) get legal user shells 

getut(3C): getutent ( ) , getutid ( ) , getutline ( ) , pututline ( ) , setutent ( ) , 

endutent ( ) , utmpname ( ) access utmp file entry 

getutent ( ) : access utmp file entry see getut(3C) 

getwc(3C): getwc ( ) , getwchar ( ) , f getwc ( ) get wide character from a stream file 

getwchar ( ) : get wide character from a stream file see getwc(3C) 

getw( ) : get word from a stream file see getc(3S) 

getws(3C): getws ( ) , f getws ( ) get a wide string from a stream 

glob(3C): glob(), globfreeO filename generation function 

globf ree ( ) - file name generation function see glob(3C) 

gmtime ( ) : convert date and time to string see ctime(3C) 

gpio_get_status(3l): gpio_get_status return status lines of GPIO card 

gpio_set_ctl(3l): gpio_set_ctl set control lines on GPIO card 

gsignal ( ) : software signals see ssignal(3C) 

hasmntopt ( ) : get file system descriptor file entry see getmntent(3X) 

hcreate ( ) : manage hash search tables ..see hsearch(3C) 

hdestroyO: manage hash search tables see hsearch(3C) 

herror - resolver routines see resolver(3N) 
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hidecdf ( ) - manipulate context-dependent file path names see getcdf(3C) 

hpib_abort(3l): hpib_abort ( ) stop activity on specified HP-IB bus 

hpib_address_ctl(3l): hpib_address_ctl ( ) set HP-IB bus address for an interface 

hpib_atn_ctl(3D: hpib_atn_ctl ( ) control Attention line on HP-IB 

hpib_bus_status(3l): hpib_bus_status ( ) return status of HP-IB interface 

hpib_cardj>po!Lresp(3l): hpib_card_ppoll_resp ( ) control response to parallel poll on HP-IB 

hpib_eoi_ctl(3l): hpib_eoi_ctl ( ) control EOI mode for HP-IB file 

hpib_io(3l): hpib_io() perform I/O with an HP-IB channel from buffers 

hpib_j>arity_ctl(3l): hpib_parity_ctl ( ) enable/disable odd parity on ATN commands 

hpib_pass_ctl(3l): hpib_pass_ctl { ) change active controllers on HP-IB 

hpibj>poll(3l): hpib_ppoll ( ) conduct parallel poll on HP-IB bus 

hpib_jppoIl_resp_ctl(3l): hpib_ppoll_resp_ctl ( ) define interface parallel poll response 

hpib_ren_ctl(3l): hpib_ren_ctl() control the Remote Enable line on HP-IB 

hpib_rqst_srvce(3l): hpib_rqst_srvce ( ) allow interface to enable SRQ line on HP-IB 

hpib_send_cmnd(3I): hpib_send_cmnd ( ) send command bytes over HP-IB 

hpib_spoIl(3l): hpib_spoll ( ) conduct a serial poll on HP-IB bus 

hpib_status_wait(3l): bpib_status_wait ( ) wait until the requested status condition becomes true 

hpib_wait_on_j>poll(3l): hpib_wait_on_ppoll ( ) wait until a particular parallel poll value occurs 

hppac(3X) Series 800 HP3000-mode packed decimal library 

hsearch(3C): hsearchO, hcreateO, hdestroyO manage hash search tables 

htonl ( ) , htons ( ) : convert values from host to network byte order see byteorder(3N) 

hypot(3M): hypot ( ) , cabs ( ) Euclidean distance, complex absolute value function 

iconv(3C): iconvclose ( ) , iconvopen ( ) , iconvsize ( ) , iconvlock ( ) , 

iconv, iconvi, iconv2 code set conversion routines 

idtolang ( ) : NLS information about native languages see langinfo(3C) 

ieee(3M): copysign( ) , copysignf ( ) , drem( ) , finite ( ) , f initef ( ) , 

logb(), scalbO copysign, remainder, classification, exponent manipulations 

index ( ) : BSD portability string routine see string(3C) 

inet(3N): inet_addr ( ) , inet_network ( ) , inet_ntoa ( ) , 

inet_makeaddr ( ) , inet_lnaof ( ) , inet_netof ( ) Internet address manipulation routines 

inet_addr ( ) : Internet address manipulation routines see inet(3N) 

inet_lnaof ( ) : Internet address manipulation routines see inet(3N) 

inet_makeaddr ( ) : Internet address manipulation routines see inet(3N) 

inet_netof ( ) : Internet address manipulation routines see inet(3N) 

inet_network ( ) : Internet address manipulation routines see inet(3N) 

inet_ntoa( ) : Internet address manipulation routines see inet(3N) 

initgroups(3C): initgroups ( ) initiahze group access fist 

initopt(3N): initoptO initialize a NetlPC option buffer 

io_burst(3l): io_burst ( ) perform low-overhead I/O on an HP-IB/GPIO/parallel channel 

io_dma_ctl(3l): io_dma_ctl ( ) control DMA allocation for an interface 

io_eol_ctl(3l): io_eol_ctl set up read termination character on special file 

io_get_term_reason(3l): io_get_tenn_reason( ) determine how last read terminated 

io_interrupt_ctl(3l): io_interrupt_ctl ( ) enable/disable interrupts for the associated eid 

io_lock(3l): io_lock, io_unlock lock and unlock an interface 

io_on_interrupt(3l): io_on_interrupt ( ) device interrupt (fault) control 

io_reset(3l): io_reset ( ) reset an I/O interface 

io_speed_ctl(3l): io_speed_ctl ( ) inform system of required transfer speed 

io_timeout_ctl(3l): io_timeout_ctl ( ) establish a time limit for I/O operations 

io_unlock: lock and unlock an interface see io_lock(3l) 

io.width^ctl^I): io_width_ctl() set width of data path 

ipcerrmsg(3N): ipcerrmsg ( ) , ipcerrstr ( ) provide text describing NetlPC error number 

ipcerrstr ( ) - provide text describing NetlPC error number see ipcerrmsg(3N) 

is_68010_present: check for presence of hardware capabilities see is_h.w_present(3C) 

is_68881_present: check for presence of hardware capabilities see is_hwj»resent(3C) 

is_98248A_present: check for presence of hardware capabilities see is_hw_present(3C) 

is_98635A_present: check for presence of hardware capabilities see is_hwj>resent(3C) 

isalnum( ) : classify characters .see ctype(3C) 
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isalpha ( ) : classify characters see ctype(SC) 

isascii ( ) : classify characters see ctype(3C) 

isatty ( ) : find name of a terminal see ttyname(SC) 

iscntrl ( ) : classify characters see ctype(3C) 

isdigit ( ) : classify characters see ctype(3C) 

isgraph( ) : classify characters see ctype(3C) 

is_hwj»resent(3C): is_68010jresent, is_68881_present, 

is_98635A_present, is_98248A_present check for presence of hardware capabilities 

isinf(3M): isinf ( ) , isinf f ( ) test for INFINITY 

isinf f ( ) : test for INFINITY (float version) see isinf(3M) 

islower ( ) : classify characters see ctype(SC) 

isnan(3M): isnanO, isnanf () .test for NaN 

isnanf ( ) : test for NaN (float version) see isnan(3M 

isprint ( ) : classify characters see ctype(3C 

ispunct ( ) : classify characters see ctype(3C 

isspace ( ) : classify characters see ctype(3C 

isupper ( ) : classify characters see ctype(3CJ 

iswalnum: classify wide characters see wctype(3C 

iswalpha: classify wide characters see wctype(3C 

iswcntrl: classify wide characters see wctype(3C 

iswdigit: classify wide characters see wctype(3C! 

iswgraph: classify wide characters see wctype(3C 

iswlower: classify wide characters see wctype(3C 

iswprint: classify wide characters see wctype(3C 

iswpunct: classify wide characters ....see wctype(3C 

iswspace: classify wide characters see wctype(3CT 

iswupper: classify wide characters see wctype(3C 

iswxdigit: classify wide characters see wctype(3C 

isxdigit ( ) : classify characters see ctype(3C 

j ( ) : Bessel function see bessel(3M) 

j 1 ( ) : Bessel function .see bessel(3M) 

jn ( ) : Bessel function see bessel(3M) 

jrand48 ( ) : generate pseudo-random numbers see drand48(3C) 

l3tol(3C): 13tol ( ) , ltol3 ( ) convert between 3-byte integers and long integers 

164a: convert between long integer and base-64 ASCII string see a641(3C) 

langinfo(3C): langinf o ( ) , langtoid ( ) , idtolang ( ) , currlangid ( ) native language NLS information 

langinit ( ) : initialize the NLS environment of a program see nl_init(3C) 

langtoid( ) : NLS information about native languages see langinf o(3C) 

lcong48(): generate pseudo-random numbers see drand48(3C) 

ldcvt(3C): _ldecvt ( ) , _ldf cvt ( ) , _ldgcvt ( ) convert long double floating-point number to string 

_ldecvt ( ) - convert long double floating-point number to string see ldcvt(3C) 

ldecvt ( ) (_ldecvt ( ) ) - convert long double floating-point number to string see ldcvt(3C) 

ldexp: split floating-point into mantissa and exponent see frexp(3C) 

_ldf cvt ( ) - convert long double floating-point number to string see ldcvt(3C) 

ldf cvt ( ) (_ldf cvt ( ) ) - convert long double floating-point number to string see ldcvt(3C) 

_ldgcvt ( ) - convert long double floating-point number to string see ldcvt(3C) 

ldgcvt ( ) (_ldgcvt ( ) ) - convert long double floating-point number to string see ldcvt(3C) 

ldiv ( ) : long integer division and remainder see div(3C) 

If ind ( ) : linear search and update ....see lsearch(3C) 

lgamma ( ) : log gamma function see gamma(3M) 

local time ( ) : convert date and time to string see ctime(3C) 

loglOO: common logarithm function seeexp(3M) 

loglOf (): common logarithm function (float version) seeexp(3M) 

log2 ( ) : base 2 logarithm function see exp(3M) 

log2f (): base 2 logarithm function (float version) see exp(3M) 

logb ( ) , scalb ( ) : exponent manipulations see ieee(3M) 

logf (): natural logarithm function (float version) seeexp(3M) 
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logname(3C): logname ( ) return login name of user 

log(): natural logarithm function seeexp(3M) 

longjmpO : restore stack environment for non-local goto see setjmp(3C) 

lrand48() : generate pseudo-random numbers see drand48(3C) 

lsearch(3C): lsearchO, lfind() linear search and update 

ltoa ( ) : long to ASCII decimal see ltostr(3C) 

ltol3 ( ) : convert between 3-byte integers and long integers see l3tol(3C) 

ltostr(3C): ltostr ( ) , ultostr ( ) , ltoa ( ) , ultoa ( ) convert long integers to strings 

mallinf o: main memory allocator see ma!loc(3C) 

malloc(3C): malloc, free, realloc, calloc, 

mallopt, mallinf o, memorymap main memory allocator 

mallopt: main memory allocator see malloc (3C) 

matherr(3M): matherr ( ) error-handling function 

mblen( ) : multibyte characters and strings conversions see multibyte(3C) 

mbstowcs ( ) : multibyte characters and strings conversions see multibyte(3C) 

mbtowc () : multibyte characters and strings conversions see multibyte(3C) 

mcrtO.o: execution startup routines seecrt0(3) 

memccpy ( ) : memory operations see memory(3C) 

memchr ( ) : memory operations see memory(3C) 

memcmp ( ) : memory operations see memory(3C) 

memcpyO: memory operations see memory(3C) 

memmove ( ) : memory operations see memory(3C) 

memory(3C): memccpy ( ) , memchr ( ) , memcmp ( ) , memcpy ( ) , memset ( ) memory operations 

memorymap: main memory allocator see malloc (3C) 

memset ( ) : memory operations see memory(3C) 

mf rtO .o: execution startup routines see crt0(3) 

mkfifo(3C): mkf if o ( ) make a FIFO special file 

mktemp(3C): mktemp ( ) make a unique file name 

mktime ( ) : create calendar time value see ctime(3C) 

mktimer(3C): mktimer allocate a per-process timer 

modf : split floating-point into mantissa and exponent see frexp(3C) 

monitor (3C): monitor ( ) prepare execution profile 

mount(3N): mount ( ) keep track of remotely mounted filesystems 

mrand48(): generate pseudo-random numbers see drand48(3C) 

multibyte(3C) : mblen ( ) , mbtowc ( ) , mbstowcs ( ) , wctomb ( ) , 

wcstombs ( ) multibyte characters and strings conversions 

ndbm(3X): dbm_open, dbm_close, dbm_f etch, dbm_store, dbm_delete, dbm_f irstkey, 

dbm_nextkey, dbm_error, dbm_clearerr database subroutines 

net_aton(3C): net_aton ( ) , net_ntoa ( ) network station address string conversion routines 

net_ntoa ( ) : network station address string conversion routines see net_aton(3C) 

nextkey ( ) : database subroutines see dbm(3X) 

nlappend(3X): nlappend ( ) append appropriate language identification to valid MPE file name 

nl_asctim( ) e: convert date and time to string see ctime(3C) 

nl_ascxtime ( ) : convert date and time to string see ctime(3C) 

nl_atof : convert string to double-precision number see strtod(3C) 

nlcollate(3X): nlcollate ( ) compare strings using MPE language-dependent collating sequence 

nl_conv(3C): nl_toupper ( ) , nl_tolower ( ) translate characters for use with NLS 

nlconvclock(3X): nlconvclock ( ) check and convert time string to MPE internal format 

nlconvcustdate(3X): nlconvcustdate ( ) convert date string to MPE packed date format 

nlconvnum(3X): nlconvnum( ) convert MPE native language formatted number to ASCII number 

nl_ctime ( ) : convert date and time to string see ctime(3C) 

nl_ctype(3C): nl_isalpha ( ) , nl_isupper ( ) , nl_islower ( ) , nl_isdigit ( ) , nl_isxdigit ( ) , 

nl_isalnum( ) , nl_isspace ( ) , nl_ispunct ( ) , nl_isprint ( ) , nl_isgraph( ) , 

nl_iscntrl ( ) classify characters for use with NLS 

nl_cxtime ( ) : convert date and time to string see ctime(3C) 

nlfindstr(3X): nlf indstr ( ) search for string in another string using MPE character set definition 

nlfmtcal(3X): nlfmtcalendar ( ) format MPE packed date using localized format 
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nlfmtclock(SX): nlfmtclock ( ) format MPE time of day using localized format 

nlfmtcustdate(3X): nlfmtcustdate ( ) format MPE packed date using custom date 

nlfmtdate(3X): nlfmtdate ( ) format MPE date and time in localized format 

nlfmtlongcal(3X): nlfmtlongcal ( ) format MPE packed date using long calendar format 

nlfmtnum(3X): nlf mtnum( ) convert ASCII number to MPE language-specific formatted number 

nl_fprintf ( ) : print formatted output see printf(3S) 

nl_f scanf : formatted input conversion, read from stream file see scanf(3S) 

nl_gcvt ( ) : convert floating-point number to string see ecvt(3C) 

nlgetlang(3X): nlgetlang ( ) return current user, data, or system default language 

nlinfo(3X): nlinf o ( ) return MPE language-dependent information 

nl_init(3C): nl_init ( ) , langinit ( ) initialize the NLS environment of a program 

nl_isalnum( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isalpha ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_iscntrl ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isdigit ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isgraph() : classify characters for use with NLS see nl_ctype(3C) 

nl_islower ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isprint ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_ispunct ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isspace ( ) : classify characters for use with NLS see nl_ctype(3C) 

nlist(3C): nlist ( ) get entries from name list 

nl_isupper ( ) : classify characters for use with NLS see nl_ctype(3C) 

nl_isxdigit ( ) : classify characters for use with NLS see nl_ctype(3C) 

nljudge(3X): nljudge ( ) judge whether character is one- or multi-byte Asian using MPE character table 

nlkey compare (3X) : 

nlkeycompare ( ) compare character arrays (keyl, key2) using MPE collation table 

nl_nl_langinfo(3C): nl_langinf o ( ) NLS information about native languages 

nlnumspec(3X): nlmimspec ( ) return number convert/format information for MPE routines 

nl_printf ( ) : print formatted output see printf(3S) 

nlrepchar(3X): nlrepchar ( ) replace non-displayable characters MPE character set table 

nl_scanf : formatted input conversion, read from stream file see scanf(3S) 

nlscanmove(3X): nlscanmove ( ) .... move, scan and case shift character strings using MPE character set table 

nl_sprintf ( ) : print formatted output see printf(3S) 

nl_s scanf: formatted input conversion, read from stream file see scanf(3S) 

nl_strcmp, nl_8trncmp: character string operations see string(3C) 

nl_string(3C): strcmp8 ( ) , strncmp8 ( ) , strcmpl6 ( ) , strncmpl6 ( ) non-ASCII string collation 

nl_strtod: convert string to double-precision number see strtod(3C) 

nlsubstr(3X): nlsubstrO extract substring using MPE character set table 

nlswitchbuf(3X): nlswitchbuf ( ) convert string screen order using MPE character set table 

nl_tolower() : translate characters for use with NLS see nl_conv(3C) 

nl_tools_16(3C): f irstof 2 ( ) , secof 2 ( ) , byte_status ( ) , c_colwidth( ) , 

FIRSTC-f 2 ( ) , SECof 2 ( ) , BYTE_STATUS ( ) , C_COLWIDTH ( ) , CHARAT ( ) , 

advancbo, charadvo, wcharo, wcharadvo tools to process 16-bit characters 

nl_toupper ( ) : translate characters for use with NLS see nl_conv(3C) 

retranslate (3X): nit rans late ( ) translate ASCII EBCDIC using MPE conversion table 

nrand48 ( ) : generate pseudo-random numbers see drand48(3C) 

ntohlO, ntohsO : convert values from network to host byte order see byteorder(3N) 

opendirO: directory operations see directory(3C) 

openlog ( ) : control system log see syslog(3C) 

optarg: get option letter from argument vector see getopt(3C) 

opterr: get option letter from argument vector see getopt(3C) 

optind: get option letter from argument vector see getopt(3C) 

optoverhead(3N): optoverhead( ) return number of bytes needed by aNetlPC option 

pclose ( ) : initiate pipe I/O to/from a process see popen(3S) 

perror(3C): perror(), ermoO, sys_errlist ( ) , sys_nerr() system error messages 

pfm_$intro(3): pfm_$intro fault management 

pfm_$cleanup(3): pfm_$cleanup ( ) establish a cleanup handler 
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pfm_$enable(3): pfm_$enable ( ) enable asynchronous faults 

pfm_$enable_faults(3): pfm_$enable_f aults ( ) enable asynchronous faults 

pfm_$inhibit(3): pfm_$inhibit ( ) inhibit asynchronous faults 

pfm_inhibit(3): pfm_inbibit pointer entry for conflicting online manual entries 

pfm_$inbibit_faults(3): pfm_$inhibit_f aults inhibit asynchronous faults; allow time-sliced task switching 

pfm_$init(3): pfm_$init ( ) initiahze the process fault manager package 

pfm_$reset_cleanup(3): pfm_$reset_cleanup reset a cleanup handler 

pfm_$rls_cleanup(3): pfm_$rls_cleanup( ) release a cleanup handler 

pfm_$signal(3): pf m_$signal ( ) signal the calling process 

pgni_$intro(3): pgm_$intro program management 

pgm_$e3cit(3): pgm_$exit ( ) exit a program 

popen(3S): popen( ) , pclose ( ) initiate pipe I/O to/from a process 

powf ( ) : power function (float version) see exp(3M) 

pow( ) : power function .see exp(3M) 

printf (3S) : print f ( ) , nl_pr int f ( ) , f print f ( ) , nl_f print f ( ) , 

sprintf ( ) , nl_sprintf ( ) print formatted output 

printmsg(3C): printmsg ( ) , f printmsg ( ) , sprintmsg ( ) print formatted output with numbered arguments 

ptsname(3C): ptsname get the name of a slave pty 

putc(3S): putc ( ) , putchar ( ) , fputc ( ) , putw( ) put character or word on a stream 

putchar ( ) : put character on a stream see putc(3S) 

putenv(3C): putenvO change or add value to environment 

putpwent(3C): putpwent ( ) write password file entry 

puts(3S): puts ( ) , fputs ( ) put a string on a stream 

putspwent(3C): putspwent ( ) write secure password file entry 

_pututline ( ) : access utmp file entry see getut(3C) 

pututline ( ) : access utmp file entry see getut(3C) 

putwc(3C): putwc ( ) , putwchar ( ) , fputwc ( ) , putw( ) put wide character on a stream 

putwchar ( ) : put wide character on a stream see putwc(3C) 

putw( ) : put word on a stream see putc(3S) 

putws(3C): putws ( ) , fputws (.) put a wide string on a stream 

qsort(3C): qsortO quicker sort 

rand(3C): rand( ) , srand( ) simple random-number generator 

rcmd(3N): rcmd(), rresvportO, ruserokO return a stream to a remote command 

readdir ( ) : directory operations see directory(3C) 

readopt(3N): readopt ( ) obtain option code and data from NetlPC option buffer 

realloc: main memory allocator see malloc(3C) 

regcmp(SX): regcmp( ) , regex( ) compile and execute regular expression 

regcomp(3C): regcomp ( ) , regerror ( ) , regexec ( ) , regf ree ( ) regular expression matching routines 

regerrorO - regular expression matching routines see regcomp(3C) 

regexO : compile and execute regular expression see regcmp(3X) 

regexec ( ) - regular expression matching routines see regcomp(3C) 

regexp(3X): compile ( ) , step ( ) , advance ( ) regular expression compile and match routines 

regf ree ( ) - regular expression matching routines see regcomp(3C) 

reltimer(3C): reltimer relatively arm a per-process timer 

remexportent ( ) - access exported file system information see exportent(3N) 

remove(3C): remove ( ) i-emove a file 

rea_init, res_mkquery, res_query, res_search, res_send, - resolver routines see resolver(3N) 

resolver(3N): res_init, res_mkquery, res_query, res_search, res_send, dn_comp, 

dn_expand, herror .resolver routines 

rewinddir ( ) : directory operations see directory(3C) 

rewind: reposition a file pointer in a stream see fseek(3S) 

rexec(3N): rexecO return stream to a remote command 

rindex ( ) : BSD portability string routine see string(3C) 

rint ( ) : round-to-nearest function see floor(3M) 

rmtimer(3C): rmtimer free a per-process timer 

rnusers(3N): rnusers ( ) , rusers ( ) return information about users on remote machines 

rpc(3C): rpc ( ) library routines for remote procedure calls 
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rrosvport ( ) - return a stream to a remote command see rcmd(3N) 

rstat(3N): rstat ( ) , havedisk( ) get performance data from remote kernel 

ruserok ( ) return a stream to a remote command see rcmd(3N) 

rwall(3N): rwall ( ) write to specified remote machines 

scalb ( ) , logb ( ) : exponent manipulations see ieee(3M) 

scandir(3C): scandir ( ) , alphasort ( ) scan a directory 

scais£(3S); scanf { ) , f scanf ( ) , sseanf ( ) nl_seas£ - 

nl_f scanf, nl_s scanf formatted input conversion, read from stream file 

secof 2 ( ) , seco£2 () : process 16-bit characters see nl_tools_16(3C) 

seed48 ( ) : generate pseudo-random numbers see drand48(3C) 

seekdir ( ) : directory operations see directory(3C) 

setaclentry(3C): setaclentry ( ) , f setaclentry ( ) add, modify, or delete access control list entry 

setbuf(3S): setbuf ( ) , setvbuf ( ) assign buffering to a stream file 

setccent ( ) : get cluster configuration entry see getccent(3C) 

setclock(3C): setclock set value of system-wide clock 

setexportent ( ) - access exported file system information see exportent(3N) 

setf sent ( ) : get file system descriptor file entry see getfsent(3X) 

setgrent ( ) : get group file entry see getgrent(3C) 

sethostent ( ) : get network host entry see gethostent(3N) 

setjmp(SS): set jmp ( ) , longjmp ( ) save/restore stack environment for non-local goto 

_setjmp() : save stack environment for non-local goto see setjmp(3C) 

setkey ( ) : generate hashing encryption see crypt(3C) 

setlocale(3C): set locale ( ) , getlocale ( ) set and get the locale of a program 

setlogmask ( ) : control system log see syslog(3C) 

setmntent ( ) : get file system descriptor file entry see getmntent(3X) 

setnetent ( ) : get network entry see getnetent(3N) 

setprotoent ( ) : get protocol entry see getprotoent(3N) 

setpwent ( ) : get password file entry see getpwent(3C) 

setpwent ( ) : get secure password file entry see getspwent(3C) 

setservent ( ) : get service entry see getservent(3N) 

setusershell ( ) - rewind legal user shells file see getusershell(3C) 

setutent ( ) : access utmp file entry see getut(3C) 

setvbuf ( ) : assign buffering to a stream file see setbuf(3S) 

sgetl ( ) : access long integer data in a machine-independent fashion see sputl(3X) 

shl_def inesym( ) - define new symbol for shared libraries see shl_load(3X) 

shl_findsym() - exph\rit load of shared libraries see shl_load(3X) 

shl_f indsym( ) - get information about shared libraries see shl_load(3X) 

shl_gethandle ( ) - get shared hbrary information see shl_load(3X) 

shl_load(3X): shl_load( ) , shl_f indsym( ) , shl_unload( ) , shl_get ( ) explicit load of shared libraries 

shl_load( ) - explicit load of shared libraries see shl_load(3X) 

shl_unload( ) - unload shared libraries see shl_load(3X) 

sigaddset ( ) : initiahze, manipulate, and test signal sets see sigsetops(3C) 

sigdelset ( ) : initiahze, manipulate, and test signal sets see sigsetops(3C) 

sigemptyset ( ) : initiahze, manipulate, and test signal sets see sigsetops(3C) 

sigf illset ( ) : initiahze, manipulate, and test signal sets see sigsetops(3C) 

sigismember ( ) : initiahze, manipulate, and test signal sets see sigsetops(3C) 

signgam( ) : log gamma function see gamma(3M) 

sigsetops(3C): sigemptyset ( ) , sigf Illset ( ) , sigaddset ( ) , 

sigdelset (), sigismember () initialize, manipulate, and test signal sets 

sindf ( ) : trigonometric sine function (float, degrees) see trigd(3M) 

sind( ) : trigonometric sine function (degrees) see trigd(3M) 

sinf ( ) : trigonometric sine function (float) see trig(3M) 

sinh(3M): sinh( ) , cosh( ) , tanh( ) , sinhfO, coshf ( ) , tanhf ( ) hyperbolic functions 

sinhf ( ) : hyperbolic cosine function (float version) see sinh(3M) 

sin( ) : trigonometric sine function see trig(3M) 

sleep(3C): sleep ( ) suspend execution for interval 

spray(3N): spray scatter data for network checking 
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sprint £ ( ) : print formatted output see printf(3S) 

sprintmsgO: print formatted output with numbered arguments see printmsg(3C) 

sputl(3X): sputl ( ) , sgetl ( ) access long integer data in a machine-independent fashion 

sqrtf ( ) : square root function (float version) see exp(3M) 

sqrt ( ) : square root function see exp(3M) 

srand48 (): generate pseudo-random numbers see drand48(3C) 

srand ( ) : simple random-number generator see rand(3C) 

sscanf ( ) : formatted input conversion, read from stream file see scanf(3S) 

ssignal(3C): ssignal ( ) , gsignal ( ) software signals 

statfsdev(3C): statfsdevO, fstatf sdev() get file system statistics 

stdio(3S): stdio( ) standard buffered input/output stream file package 

stdipc(3C): ftok() standard interprocess communication package 

step ( ) : regular expression compile and match routines see regexp(3X) 

store ( ) : database subroutines see dbm(3X) 

strcat ( ), strncat ( ) : character string operations see string(3C) 

strchr (), strrchr() : character string operations see string(3C) 

strcmp8 ( ) , strcmpl6 ( ) : non-ASCII string collation see nl_string(3C) 

strcmpO, strncmpO: character string operations see string(3C) 

strcoll ( ) : character string operations see string(3C) 

strcpyO, strncpyO : character string operations see string(3C) 

strerrorO: system error messages see perror(3C) 

strftime(3C): strf time ( ) convert date and time to string 

string(3C): strcat ( ) , strncat ( ) , strcmp ( ) , strncmp ( ) , strcpy ( ) , strncpy ( ) , strlen ( ) , 

strchr ( ) , strrchr ( ) , strpbrk ( ) , strspn ( ) , strcspn ( ) , 

strtokO, nl_strcmp, nl_strncmp character string operations 

strlen(): character string operations see string(3C) 

strncmp8 ( ) , strncmpl6 ( ) : non-ASCII string collation see nl_string(3C) 

strord(3C): strord( ) convert string data order 

strpbrk (): character string operations see string(3C) 

strrstr ( ) : character string operations see string(3C) 

strspnO, strcspnO: character string operations see string(3C) 

strstr ( ) : character string operations see string(3C) 

strtoacl(3C): strtoacl ( ) , strtoaclpatt ( ) convert string form to access control list structure 

strtoaclpatt ( ) : convert pattern string form to access control fist (ACL) structure see strtoacl(3C) 

strtod(3C): strtod ( ) , atof ( ) , nl_strtod, nl_atof convert string to double-precision number 

strtok ( ) : character string operations see string(3C) 

strtold(3C): strtoldO convert string to long double-precision number 

strxfrmO: character string operations see string(3C) 

swab(3C): swab() swap bytes 

sys_errlist: system error messages see perror(3C) 

syslog(3C): syslogO, openlogO, closelogO, setlogmaskO control system log 

sys_nerr: system error messages see perror(3C) 

system(3S): system ( ) issue a shell command 

tandf ( ) : trigonometric tangent function (float, degrees) see trigd(3M) 

tand( ) : trigonometric tangent function (degrees) see trigd(3M) 

tanf ( ) : trigonometric tangent function (float) see trig(3M) 

tanhf ( ) : hyperbolic tangent function (float version) see sinh(3M) 

tanh ( ) : hyperbolic tangent function see sinh(3M) 

tan(): trigonometric tangent function seetrig(3M) 

tcattribute(3C): tcgetattr ( ) , tcsetattr ( ) ...control tty device 

tccontrol(3C): tcsendbreak ( ) , tcdrain(), tcflushO, tcflowO tty line control functions 

tcdrainO: tty fine control functions see tccontrol(3C) 

tcf low ( ) : tty fine control functions see tccontrol(3C) 

tcf lush ( ) : tty fine control functions , see tccontrol(3C) 

tcgetattr () : get tty device attributes see tcattribute(3C) 

tcgetpgrp(3C): tcgetpgrp ( ) get foreground process group ID 

tcsendbreak ( ) : tty line control functions see tccontrol(3C) 
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tcsetattr ( ) : set tty device attributes see tcattribute(SC) 

tcsetpgrp(3C): tcsetpgrp ( ) get foreground process group ID 

tdelete ( ) : manage binary search trees see tsearch(3C) 

telldir ( ) : directory operations see directory(SC) 

tempnam( ) : create a name for a temporary file see tmpnam(3S) 

termcap(3X): tgetent ( ) , tgetnum( ) , tgetf lag ( ) , tgetstr ( ) , 

tgoto ( ) , tputs ( ) emulate /etc/termcap access routines 

tfind() : manage binary search trees see tseareli(SC) 

tgetent ( ) : emulate /etc/termcap access routines see termcap(3X) 

tgetf lag ( ) : emulate /etc/termcap access routines see termcap(3X) 

tgetnum( ) : emulate /etc/termcap access routines see termcap(3X) 

tgetstr ( ) : emulate /etc/termcap access routines see termcap(3X) 

tgoto () : emulate /etc/termcap access routines see termcap(3X) 

timezone ( ) : convert date and time to string see ctime(3C) 

tmpfile(3S): tmpf ile ( ) create a temporary file 

tmpnam(3S): tmpnam( ) , tempnam( ) create a name for a temporary file 

toascil ( ) : translate characters see conv(3C) 

tolower ( ) , _tolower: translate characters see conv(3C) 

toupper ( ) , _toupper: translate characters see conv(3C) 

towlower ( ) : translate wide characters see wconv(3C) 

towupper ( ) : translate wide characters see wconv(3C) 

tputs ( ) : emulate /etc/termcap access routines see termcap(3X) 

trig(3M): sin(), cos (), tan(), asin(), acos(), atan(), atan2 (), sinf (), cosf (), tanf (), 

asinf ( ) , acosf ( ) , atanf ( ) , atan2f ( ) trigonometric functions 

trigd(3M) : s ind ( ) , cosd ( ) , tand ( ) , as ind ( ) , acosd ( ) , atand ( ) , at an2d ( ) , 

sindf ( ) , cosdf ( ) , tandf ( ) , asindf ( ) , acosdf ( ) , atandf ( ) , 

atan2df ( ) degree-valued trigonometric functions 

tsearch(3C): tsearchO, tfindO, tdelete (), twalk ( ) manage binary search trees 

ttyname(3C): ttynameO, isattyO find name of a terminal 

ttyslot(3C): ttyslot ( ) find the slot in the utmp file of the current user 

twalk ( ) : manage binary search trees see tsearch(3C) 

tzname ( ) : convert date and time to string see ctime(3C) 

tzset ( ) : convert date and time to string see ctime(3C) 

ultoa ( ) : unsigned long to ASCII decimal see ltostr(3C) 

ultostr ( ) : unsigned long to ASCII see ltostr(3C) 

undialO : establish an out-going terminal fine connection see dial(3C) 

ungetc(3S): ungetc ( ) push character back into input stream 

ungetwc(3C): ungetwc ( ) push wide character back into input stream 

utmp file entry see getut(3C) 

utmpname ( ) : access utmp file entry see getut(3C) 

vfprintf ( ) : print formatted output of a varargs argument fist see vprintf(3S) 

vf scanf ( ) : formatted input conversion to a varargs argument see vscanf(3S) 

vprintf(3S): vprintf ( ) , vfprintf ( ) , vsprintf ( ) print formatted output of a varargs argument fist 

vscanf(3S): vscanf ( ) , vf scanf ( ) , vsscanf ( ) formatted input conversion to a varargs argument 

vsprintf ( ) : print formatted output of a varargs argument list see vprintf(3S) 

vsscanf ( ) : formatted input conversion to a varargs argument see vscanf(3S) 

wcharadvo: process 16-bit characters see nl_tools_16(3C) 

wcharo : process 16-bit characters see nl_tools_16(3C) 

wconv(3C): towupper ( ) , towlower ( ) translate wide characters 

wcscat, wcsncat: wide character string operations see wcstring(3C) 

wcschr, wcsrchr: wide character string operations see wcstring(3C) 

wcscmp, wcsncmp: wide character string operations see wcstring(3C) 

wcscoll: wide character string operations see wcstring(3C) 

wcscpy, wcsncpy: wide character string operations see wcstring(3C) 

wcsftime(3C): wcsf time ( ) convert date and time to wide-character string 

wcslen: wide character string operations see wcstring(3C) 

wcspbrk: wide character string operations see wcstring(3C) 
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wcsspn, wcscspn: wide character string operations see wcstring(3C) 

wcstod(3C): wcstod( ) convert wide character stringto double-precision number 

wcstok: wide character string operations see wcstring(3C) 

wcstring(3C): wcscat, wcsncat, wcscmp, wcsncmp, wcscpy, wcsncpy, wcslen, wcschr, wcsrchr, 

wcspbrk, wc&spn, wcscspn, wcstok, nl_wcscmp, nl_wcsncmp wide character string operations 

wcswcs: wide character string operations see wcstring(3C) 

wcswidth: wide character string operations see wcstring(3C) 

wctomb ( ) , wctombs ( ) : multibyte characters and strings conversions see multibyte(3C) 

wctype(3C): iswalpha, iswupper, iswlower, iswdigit, iswxdigit, iswalnum, iswspace, 

iswpunct, iswprint, iswgraph, iswcntrl classify wide characters 

wcwidth: wide character string operations see wcstring(SC) 

wordexp 3C: wordexp, wordf ree - perform word expansions 

xdr(3C): xdr() library routines for external data representation 

yO ( ) : Bessel function see bessel(3M) 

yl ( ) : Bessel function see bessel(3M) 

yn ( ) : Bessel function see bessel(3M) 

yp_all ( ) - Network Information Service client interface see ypclnt(3C) 

yp_bind() - Network Information Service client interface see ypclnt(3C) 

ypckit(3C): ypclnt ( ) , yp_all ( ) , ypjbind ( ) , yp_f irst ( ) , yp_get_def ault_domain ( ) , 

yp_master ( ) , yp_match ( ) , yp_next ( ) , yp_order ( ) , yp_unbind ( ) , 

yperr_string ( ) , ypprot_err ( ) Network Information Service client interface 

yperr_string() - Network Information Service client interface see ypclnt(3C) 

yp_f irst ( ) - Network Information Service client interface see ypclnt(3C) 

yp_get_def ault_domain ( ) - Network Information Service client interface see ypclnt(3C) 

yp_master ( ) - Network Information Service client interface see ypclnt(3C) 

yp_niatch( ) - Network Information Service client interface see ypclnt(3C) 

yp_next ( ) - Network Information Service client interface see ypclnt(3C) 

yp_order ( ) - Network Information Service client interface see ypclnt(3C) 

yppasswd(3N): yppasswd( ) update user password in Network Information Service 

ypprot_err() - Network Information Service client interface see ypclnt(3C) 

yp_unbind( ) - Network Information Service client interface see ypclnt(3C) 
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NAME 

intro - introduction to system calls 

DESCRIPTION 

This section describes all of the system calls. All of these calls return a function result. This result indi- 
cates the status of the call. Typically, a zero or positive result indicates that the call completed successfully, 
and -1 indicates an error. The individual descriptions specify the details. An error number is also made 
available in the external variable errno (see errno{2)). Note: errno is not cleared on successful calls. 
Therefore, it should be tested only after an error has been indicated. 

SEE ALSO 

intro(3), errno(2), hier(5). 

The introduction to this manual. 
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NAME 

accept - accept a connection on a socket 

SYNOPSIS 

#include < sys/ socket .h> 

AF_CCITT only: 

#include <x25/x25addrstr.h> 

int accept (Int s, void *addr, int *addrlen) ; 

DESCRIPTION 

accept ( ) is used with connection-based socket types, such as SOCK_STREAM. Argument s is a socket 
descriptor created using socket ( ) , bound to an address by bind ( ) , and listening for connections after a 
listen ( ) . accept ( ) extracts the first connection on the queue of pending connections, creates a new 
socket with the same properties as s, and allocates a new file descriptor, ns, for the socket. If no pending 
connections are present on the queue and non-blocking mode has not been enabled using the 
0_NONBLOCK or 0_NDELAY fcntl() flags or the PIOSNBIO ioctlO request, accept ( ) blocks 
the caller until a connection is present. (0_NONBLOCK and 0_NDELAY are defined in <sys/f cntl .h>; 
see fcntl(2) fcntl(5), and socket(7). FIOSNBIO and the equivalent request PIONBIO are defined in 
<sys/ioctl .h>, although use of PIONBIO is not recommended; see ioctl(2), ioctl(5\ and socket(7).) If 
the socket is marked non-blocking and no pending connections are present on the queue, accept ( ) 
returns an error as described below. The accepted socket, ns, cannot be used to accept more connections. 
The original socket s remains open. It is possible to determine whether a listening socket has pending con- 
nection requests ready for an accept () call by using select () for reading. 

The argument addr should point to a local socket address structure. The accept ( ) call fills in this struc- 
ture with the address of the connecting entity, as known to the underlying protocol. The format of the 
address depends upon the protocol and the address-family of the socket s. addrlen is a pointer to an int; it 
should initially contain the size of the structure pointed to by addr. On return, it contains the actual length 
(in bytes) of the address returned. If the memory pointed to by addr is not large enough to contain the 
entire address, only the first addrlen bytes of the address are returned. 

Since both the fcntl() 0_NONBLOCK flag and PIOSNBIO ioctlO request are supported, some 
clarification on how these features interact is necessary. If the 0_NONBLOCK flag has been set, 
accept ( } requests behave accordingly, regardless of any PIOSNBIO requests. If the 0_NONBLOCK 
flag has not been set, PIOSNBIO requests control the behavior of accept ( ) . AP_CCITT only: The addr 
parameter to accept ( ) returns addressing information for the connecting entity, except for the 
x2 5if name [ ] field of addr which contains the name of the local X.25 interface through which the connec- 
tion request arrived. Call-acceptance can be controlled with the X25_CALL_ACPT_APPROVAL 
ioct 1 ( ) call described in socketx25(7). 

RETURN VALUE 

Upon successful competion, accept ( ) returns a non-negative integer which is a descriptor for the 
accepted socket. If an error occurs, accept ( ) returns -1 and sets errno to indicate the cause. 

DIAGNOSTICS 

accept ( ) fails if any of the following conditions are encountered: 

[EBADF] The file descriptor s is invalid. 

[ENOTSOCK] The file descriptor s references a file, not a socket. 

[EOPNOTSUPP] The socket referenced by s is not of type SOCK.STREAM. 

[EFAULT] The addr parameter is not in a valid pointer. 

[EWOULDBLOCK] Non-blocking I/O is enabled using 0_NDELAY or PIOSNBIO and no con- 

nections are present to be accepted. 

[EMFILE] The maximum number of file descriptors for this process are already 

currently open. 

[ENFILE] The system's table of open files is full and no more accepts can be 

accepted at this time. 
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[ENOBUFS] 
[EINVAL] 

[EAGAIN] 
[EINTR] 



No buffer space is available. The accept ( ) cannot complete. The 
queued socket connect request is aborted. 

The socket referenced by s is not currently a listen socket or has been 
shutdown(). A listenO must be done before an accept ( ) is 
allowed. 

Non-blocking I/O is enabled using 0_NONBLOCK and no connections are 
present to be accepted. 

The call was interrupted by a signal before a valid connection arrived. 



I 



AUTHOR 

accept ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

bind(2), connect(2), listen(2), select(2), socket(2) socketx25(7). 
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NAME 

access - determine accessibility of a file 

SYNOPSIS 

#include <unistd.h> 

int access (char *path, int amode); 

DESCRIPTION 

path points to a path name naming a file, access ( ) checks the named file for accessibility according to 
the bit pattern contained in amode, using the real user ID instead of the effective user ID and the real group 
ID instead of the effective group ID. The value of amode is either the bit- wise inclusive OR of the access per- 
missions to be checked or the existence test. The following symbolic constants, defined in <unistd.h>, 
test for permissions: 

R_OK read 

W_OK write 

X_OK execute (search) 

P_OK check existence of file 

Access Control Lists (ACLs) 

Read, write and execute/search permissions are checked against the file's access control list. Each mode is 
checked separately since different ACL entries might grant different permissions. The real user ID is com- 
bined with the process's real group ID and each group in its supplementary groups list, and the access con- 
trol list is searched for a match. Search proceeds in order of specificity and ends when one or more match- 
ing entries are found at a specific level. More than one u.g or %.g entry can match a user if that user has a 
non-null supplementary groups list. If any matching entry has the appropriate permission bit set, access is 
permitted. 

access () reports that a shared text file currently open for execution is not writable, regardless of its 
access control list. It also reports that a file on a read-only file system is not writable. However, 
access ( ) does not report that a shared text file open for writing is not executable, since the check is not 
easily done. 

RETURN VALUE 

If the requested access is permitted, a value of is returned. Otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

Access to the file is denied if one or more of the following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] Read, write, or execute (search) permission is requested for a null path name. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EROFS] Write access is requested for a file on a read-only file system. 

[ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being exe- 

cuted. 

[EACCES] The access control list does not permit the requested access and the real user ID is not 

a user with appropriate privileges. 

[EFAULT] path points outside the allocated address space for the process. The reliable detection 

of this error is implementation dependent. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

The owner of a file has permission checked with respect to the "owner" read, write, and execute mode bits. 
Members of the file's group other than the owner have permissions checked with, respect to the "group" 
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mode bits, and all others have permissions checked with respect to the "other" mode bits. 

access ( ) reports that a file currently open for execution is not writable, regardless of the setting of its 
mode. 

WARNINGS 

If the path is valid and the real user ID is super-user, and the access requested is not X_OK, access ( ) 
always returns 0. If X_OK access is requested for a valid path and the real user ID is super-user and the 
file is a directory, access always returns 0. If X_OK access is requested for a valid path which is not a 
directory and the real user ID is super-user, access returns only if at least one execute bit (for user, group, 
or other^ is set in the file's mode. 

Access Control Lists 

Access control fist descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

SEE ALSO 

chmod(2), setacl(2), stat(2), acl(5), unistd(5). 

STANDARDS CONFORMANCE 

access ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
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NAME 

acct - enable or disable process accounting 

SYNOPSIS 

ttinclude <sys/acct.h> 

int acct (const char *path) ; 

DESCRIPTION 

acct ( ) is used to enable or disable the system's process accounting routine. If the routine is enabled, an 
accounting record is written on an accounting file for each process that terminates. Termination can be 
caused by one of two things: an exit ( ) call or a signal; see exit(2) and signal(5). The effective user ID of 
the calling process must be super-user to use this call. 

path points to a path name naming the accounting file. The accounting file format is described in acct(A). 

The accounting routine is enabled Si path is non-zero and no errors occur during the system call. It is dis- 
abled if path is zero and no errors occur during the system call. 

When the amount of free space on the file system containing the accounting file falls below a configurable 
threshold, the system prints a message on the console and disables process accounting. Another message is 
printed and the process accounting is re-enabled when the space reaches a second configurable threshold. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

acct ( ) fails if one or more of the following is true: 

[EPERM] The effective user ID of the calling process is not super-user. 

[EBUSY] An attempt is being made to enable accounting when it is already enabled. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] One or more components of the accounting file path name do not exist. 

[EACCES] The file named by path is not an ordinary file. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path points to an illegal address. The reliable detection of this error simplementation 

dependent. 

[ETXTBSY] path points to a text file which is currently open. 

[ENAMETOOLONG] 

The accounting file path name exceeds PATH_MAX bytes, or the length of a component of 
the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

DEPENDENCIES 

Series 300/400 

The system's process accounting routine ignores any locks placed on the process accounting file. 

If the size of the process accounting file reaches 5000 blocks, records for processes terminating after 
that point will be silently lost. However, in that case the turnacct command would still sense that 
process accounting is still enabled. This loss of records can be prevented by the use of ckpacct (see 
acctsh(WL)). 

SEE ALSO 

acct(lM), acctsh(lM), exit(2), acct(4), signal(5). 

STANDARDS CONFORMANCE 

acct ( ) : SVID2, XPG2 
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NAME 

alarm - set a process's alarm clock 

SYNOPSIS 

#include <unistd.h> 

unsigned int alarm (unsigned int sec); 

DESCRIPTION 

alarm ( ) instructs the alarm clock of the calling process to send the signal SIGALRM to the calling process 
after the number of real-time seconds specified by sec have elapsed; see signal(5). Specific implementations 
might place limitations on the maximum supported alarm time. The constant MAX.ALARM defined in 
<sys /par am . h> specifies the implementation-specific maximum. Whenever sec is greater that this max- 
imum, it is silently rounded down to it. On all implementations, MAX_ALARM is guaranteed to be at least 
31 days (in seconds). 

Alarm requests are not stacked; successive calls reset the alarm clock of the calling process. 

If sec is 0, any previously made alarm request is canceled. 

Alarms are not inherited by a child process across a fork ( ) , but are inherited across an exec ( ) . 

On systems that support the getitimer() and setitimer() system calls, the timer mechanism 
used by alarm ( ) is the same as that used by ITIMER_REAL. Thus successive calls to alarm ( ) , get i- 
timer(),and setitimerO set and return the state of a single timer. In addition, alarm () sets the 
timer interval to zero. 

RETURN VALUE 

alarm ( ) returns the amount of time previously remaining in the alarm clock of the calling process. 

WARNINGS 

In some implementations, error bounds for alarm are -1, +0 seconds (for the posting of the alarm, not the 
restart of the process). Thus a delay of 1 second can return immediately. The setitimerO routine can 
be used to create a more precise delay. 

SEE ALSO 

sleep(l), exec(2), getitimer(2), pause(2), signal(5), sleep(3C). 

STANDARDS CONFORMANCE 

alarm ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

atexit - register a function to be called at program termination 

SYNOPSIS 

# include <stdlib.h> 

int atexit (void (*func) (void) ) ; 

DESCRIPTION 

atexit ( ) registers the function func to be called, without arguments, at normal program termination. 
Functions registered by atexit ( ) are called in reverse order of registration. 

An atexit ( ) call during exit processing is always unsuccessful. 

The number of registered functions should not exceed ATEXIT_MAX as specified in <1 imi t s . h>. 

RETURN VALUE 

atexit ( ) returns zero if the registration is successful; non-zero if unsuccessful. 

SEE ALSO 

exit(2). 

STANDARDS CONFORMANCE 

atexit ( ) : AES, XPG4, ANSI C 
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NAME 



audctl - start or halt the auditing system and set or get audit files 

SYNOPSIS 

#include <sys/audit .h> 

int audctl (int cmd, char * cpath, char *npath, mode_t mode); 

DESCRIPTION 

audctl ( ) sets or gets the auditing system "current" and "next" audit files, and starts or halts the audit- 
ing system. This call is restricted to superusers. cpath and npath hold the absolute path names of the 
"current" and "next" files, mode specifies the audit file's permission bits, cmd is one of the following 
specifications: 



AUD ON 



AUD GET 



AUD SET 



AUD SETCURR 



AUD SETNEXT 



AUD SWITCH 



The caller issues the AUD_ON command with the required "current" and "next" 
files to turn on the auditing system. If the auditing system is currently off, it is 
turned on; the file specified by the cpath parameter is used as the "current" 
audit file, and the file specified by the npath parameter is used as the "next" 
audit file. If the audit files do not already exist, they are created with the mode 
specified. The auditing system then begins writing to the specified "current" file. 
An empty string or NULL npath can be specified if the caller wants to designate 
that no "next" file be available to the auditing system. If the auditing system is 
already on, no action is performed; -1 is returned and errno is set to EBUSY. 

The caller issues the AUD_GET command to retrieve the names of the "current" 
and "next" audit files. If the auditing system is on, the names of the "current" 
and "next" audit files are returned via the cpath and npath parameters (which 
must point to character buffers of sufficient size to hold the file names), mode is 
ignored. If the auditing system is on and there is no available "next" file, the 
"current" audit file name is returned via the cpath parameter, npath is set to an 
empty string; -1 is returned, and errno is set to ENOENT. If the auditing 
system is off, no action is performed; -1 is returned and errno is set to EAL- 
READY. 

The caller issues the AUD_SET command to change both the "current" and 
"next" files. If the audit system is on, the file specified by cpath is used as the 
"current" audit file, and the file specified by npath is used as the "next" audit 
file. If the audit files do not already exist, they are created with the specified 
mode. The auditing system begins writing to the specified "current" file. Either 
an empty string or NULL npath can be specified if the caller wants to designate 
that no "next" file be available to the auditing system. If the auditing system is 
off, no action is performed; -1 is returned and errno is set to EALREADY. 

The caller issues the AUD_SETCURR command to change only the "current" 
audit file. If the audit system is on, the file specified by cpath is used as the 
"current" audit file. If the specified "current" audit file does not exist, it is 
created with the specified mode, npath is ignored. The auditing system begins 
writing to the specified "current" file. If the audit system is off, no action is per- 
formed; -1 is returned and errno is set to EALREADY. 

The caller issues the AUD_SETNEXT command to change only the "next" audit 
file. If the auditing system is on, the file specified by npath is used as the "next" 
audit file, cpath is ignored. If the "next" audit file specified does not exist, it is 
created with the specified mode. Either an empty string or NULL npath can be 
specified if the caller wants to designate that no "next" file be available to the 
auditing system. If the auditing system is off, no action is performed; -1 is 
returned, and errno is set to EALREADY. 

The caller issues the AUD_SWITCH command to cause auditing system to 
switch audit files. If the auditing system is on, it uses the "next" file as the new 
"current" audit file and sets the new "next" audit file to NULL, cpath, npath,and 
mode are ignored. The auditing system begins writing to the new "current" file. 
If the auditing system is off, no action is performed; -1 is returned, and 
errno is set to EALREADY. If the auditing system is on and there is no 
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available "next" file, no action is performed; -1 is returned, and errno is set 
to ENOENT. 

AUD_OPP The caller issues the AUD_OPP command to halt the auditing system. If the 

auditing system is on, it is turned off and the "current" and "next" audit files are 
closed, cpath, npath, and mode are ignored. If the audit system is already off, 
-1 is returned and errno is set to EALREADY. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, -1 is returned and the global variable 
errno is set to indicate the error. 

EXAMPLES 

In the following example, audct 1 ( ) is used to determine whether the auditing system is on, and to 
retrieve the names of the audit files that are currently in use by the system. 

char c_f i le [ PATH_MAX+ 1 ] , x_f i le [ PATH_MAX+ 1 ] ; 
int mode=0600; 

if ( audct 1(AUD_get, c_file, x_file, mode)) 
switch ( errno ) { 
case ENOENT: 

strcpy(x_file, "-none-") ; 
break; 

case EALREADY: 

printf ("The auditing system is OFF\n" ); 
return 0; 
case default: 

fprintf (stderr, "Audctl failed: errno=%d\n", errno); 
return 1; 
} 

printf ("The auditing system is ON: c_file=%s x_f ile=%s\n", c_file, x_file 
return 0; 

ERRORS 

audctl ( ) fails if one of the following is true: 

[EPERM] The caller does not have superuser privilege, or one or both of the given files are 

not regular files and cannot be used. 

[EALREADY] The AUD_OPP, AUD_SET, AUD_SETCURR, AUD_SETNEXT, AUD_SWITCH, or 

AUD_GET cmd was specified while the auditing system is off. 

[EBUSY] User attempt to start the auditing system failed because auditing is already on. 

[EFAULT] Bad pointer. One or more of the required function parameters is not accessible. 

[EINVAL] The cpath or npath is greater than PATH_MAX in length, the cpath or npath 

specified is not an absolute path name. 

[ENOENT] No available "next" file when cmd is AUD_GETNEXT or AUD_SWITCH. 

AUTHOR 

audctl ( ) was developed by HP. 

SEE ALSO 

audit(5), audsys(lM), audomon(lM). 
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NAME 

auds witch - suspend or resume auditing on the current process 

SYNOPSIS 

# include <sys/audit.h> 

int audswitch(int af lag) ; 

DESCRIPTION 

audswitch () suspends or resumes auditing within the current process. This call is restricted to 
su perusers. 

One of the following aflags must be used: 

AUD_SUSPEND Suspend auditing on the current process. 

AUD_RESUME Resume auditing on the current process. 

audswltch( ) can be used in self-auditing privileged processes to temporarily suspend auditing during 
intervals where auditing is to be handled by the process itself. Auditing is suspended by a call to 
audswltch ( ) with the AUD_SUSPEND parameter and resumed later by a call to audswitch ( ) with 
the AUD_RESUME parameter. 

An audswltch ( ) call to resume auditing serves only to reverse the action of a previous audswitch ( ) 
call to suspend auditing. A call to audswitch ( ) to resume auditing when auditing is not suspended has 
no effect. 

audswitch ( ) affects only the current process. For example, audswitch ( ) cannot suspend auditing 
for processes exec'ed from the current process. (Use setaudproc (see setaudproc(2)) to enable or dis- 
able auditing for a process and its children). 

RETURN VALUE 

Upon successful completion, audswitch ( ) returns 0. If an error occurs, -1 is returned and the global 
variable errno is set to indicate the error. 

ERRORS 

audswitch ( ) fails if one of the following is true: 

[EPERM] The user is not a superuser. 

[EINVAL] The input parameter is neither AUD_RESUME nor AUD_SUSPEND. 

AUTHOR 

audswitch ( ) was developed by HP. 

SEE ALSO 

audit(5), setaudproc(2), audusr(lM), audevent(lM). 
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NAME 

audwrite - write an audit record for a self-auditing process 

SYNOPSIS 

# include <sys/ audit .h> 

int audwrite (const struct self_audit_rec *audrec_p); 

DESCRIPTION 

audwrite () is called by trusted self-auditing processes, which are capable of turning off the regular 
auditing (using audswitch(2)) and doing higher-level auditing on their own. audwrite ( ) is restricted to 
superusers. 

audwrite ( ) checks to see if the auditing system is on and the calling process and the event specified are 
being audited. If these conditions are met, audwrite ( ) writes the audit record pointed to by audrec_p 
into the audit file. The record consists of an audit record body and a header with the following fields: 

u_long ah_t ime ; /* Date/time (tv_sec of timeval) */ 

u_short ahjpid; /* Process ID */ 

u_short ah_error; /* Success/failure */ 

u_short ah_event ; /* Event being audited */ 

u_short ah_len; /* Length of variant part */ 

The header has the same format as the regular audit record, while the body contains additional information 
about the high-level audit event. The header fields ah_error, ah_event, and ah_len are specified by 
the calling process, audwrite ( ) fills in ah_time and ah pid fields with the correct values, this is 
done to reduce the risk of forgery. After the header is completed, the record body is attached and the entire 
record is written into the current audit file. 

RETURN VALUE 

If the write is successful, a value of is returned. Otherwise, a value of - 1 is returned and er mo is set 
to indicate the reason for the failure. 

ERRORS 

audwrite ( ) fails if one of the following is true: 

[EPERM] The caller is not a superuser. 

[EINVAL] The event number in the audit record is invalid. 

WARNINGS 

If audwrite causes a file space overflow, the calling process might be suspended until the file space is 
cleaned up. However a returned call with the return value of indicates that the audit record has been 
successfully written. 

AUTHOR 

audwrite ( ) was developed by HP. 

SEE ALSO 

audswitch(2), audit(4). 
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NAME 

bind - bind an address to a socket 

SYNOPSIS 

#include < sys/ socket .h> 

AFJNET only: 

# include <netinet/in.h> 

AF_UNK only: 

# inc lude < sy s / un . h > 

AF_CCITT only: 

#include <x25/x25addrstr .h> 

int bind(int s, const void *addr, int addrlen) ; 

DESCRIPTION 

bind ( ) assigns an address to an unbound socket. When a socket is created with socket ( ) , it exists in 
an address space (address family) but has no address assigned, bind ( ) causes the socket whose descrip- 
tor is s to become bound to the address specified in the socket address structure pointed to by addr. 

addrlen must specify the size of the address structure. Since the size of the socket address structure varies 
between socket address families, the correct socket address structure should be used with each address 
family (for example, struct sockaddr_in for AF_INET, and struct sockaddr_un for 
AF_UNIX). Typically, the sizeof ( ) function is used to pass this value in the bind ( ) call (for exam- 
ple, sizeof (struct sockaddr_in)). 

The rules used in address binding vary between communication domains. For example, when binding an 
AP_DNIX socket to a path name (such as /tmp/my socket), an open file having that name is created in 
the file system. When the bound socket is closed, that file still exists unless it is removed or unlinked. 
When binding an AP_INET socket, sinjjort can be a port number, or it can be zero. If sin_port is zero, the 
system assigns an unused port number automatically. 

RETURN VALUE 

Upon successful completion, bind( ) returns 0; otherwise it returns -1 and sets errno to indicate the 
error. 

DIAGNOSTICS 

bind ( ) fails if any of the following conditions are encountered: 

[EBADF] s is not a valid descriptor. 

[ENOTSOCK] s is not a socket. 

[EADDRNOTAVAIL] The specified address is bad or not available from the local machine, or for 
AF_CCITT sockets which use "wild card" addressing, the specified address 
space overlays the address space of an existing bind. 

[EADDRINUSE] The specified address is already in use. 

[EINVAL] The socket is already bound to an address, the socket has been shut down, 

addrlen is a bad value, or an attempt was made to bind() an AF_UNIX 
socket to an NFS-mounted (remote) name. 

AF_CCITT: The protocol-ID length is negative or greater than 8, or the X.121 
address string contains an illegal character, or the X.121 address string is 
greater than 15 digits long. 

[EAFNOSUPPORT] Requested address does not match the address family of this socket. 

[EACCES] The requested address is protected, and the current user has inadequate per- 

mission to access it. (This error can be returned by AF_INET only.) 

[EFAULT] addr is not a valid pointer. 

[EOPNOTSUPP] The socket whose descriptor is s is of a type that does not support address bind- 

ing. 
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tENOBUFS] Insufficient buflFer memory is available. The bind ( ) cannot complete. 

[ENETUNREACH] The X.25 Level 2 protocol is down. The X.25 link is not working: wires might be 
broken, or connections are loose on the interface hoods at the modem, or the 
modem failed, or noise interfered with the line for an extremely long period of 
time. 

[EDESTADDREQ] No addr parameter was specified. 

[ENODEV] The x25ifname field name specifies a non-existent interface. (This error can be 

returned by AF_CCITT only.) 

[ENETDOWN] The x25ifname field name specifies an interface that was shut down, or never 

initialized, or whose Level 2 protocol indicates that the link is not working: 
wires might be broken, the interface hoods on the modem are broken, the 
modem failed, the phone connection failed (this error can be returned by 
AP_CCITT only), noise interfered with the line for a long period of time. 

AUTHOR 

bind ( ) was developed by the University of California, Berkeley) 

SEE ALSO 

connect(2), getsockname(2), listen(2), socket(2), af_ccitt(7F), inet(7F), socketx25(7), tcp(7P), udp(7P), 
unix(7P). 
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NAME 

brk, sbrk - change data segment space allocation 

SYNOPSIS 

#include <unistd.h> 

int brk (const void *endds) ; 
void *sbrk(int incr) ; 

DESCRIPTION 

lynainically the amount of space allocated for the calling process's 



data segment; see exec (2). The change is made by resetting the process's break value and allocating the 
appropriate amount of space. The break value is the address of the first location beyond the end of the data 
segment. The amount of allocated space increases as the break value increases. The newly allocated space 
is set to zero. 

brk ( ) sets the break value to endds and changes the allocated space accordingly. 

sbrk ( ) adds incr bytes to the break value and changes the allocated space accordingly, incr can be nega- 
tive, in which case the amount of allocated space is decreased. 

ERRORS 

brk ( ) and sbrk ( ) fail without making any change in the allocated space if one or more of the following 
are true: 

[ENOMEM] Such a change would result in more space being allocated than is allowed by a system- 

imposed maximum (see ulimit(2)). 

[ENOMEM] Such a change would cause a conflict between addresses in the data segment and any 

attached shared memory segment (see shmop(2)). 

[ENOMEM] Such a change would be impossible as there is insufficient swap space available. 

WARNINGS 

The pointer returned by sbrk ( ) is not necessarily word-aligned. Loading or storing words through this 
pointer could cause word alignment problems. 

Be very careful when using either brk or sbrk in conjunction with calls to the malloc(SC) library routines. 
There is only one program data segment from which all three of these routines allocate and deallocate pro- 
gram data memory. 

RETURN VALUE 

Upon successful completion, brk() returns a value of and sbrk() returns the old break value. Other- 
wise, a value of -1 is returned and errno is set to indicate the error. 

AUTHOR 

brk ( ) and sbrk ( ) were developed by AT&T and HP. 

SEE ALSO 

exec(2), shmop(2), ulimit(2), end(3C), malloc(3C). 

STANDARDS CONFORMANCE 

brk():XPG2 

sbrk ( ) : XPG2 
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NAME 

killpg, getpgrp, setpgrp, sigvec, signal - 4.2 BSD-compatible process control facilities 

SYNOPSIS 

#include <signal.h> 

int killpg(int pgrp, int sig); 

int getpgrp (int pid) ; 

int setpgrp (int pid, int pgrp) ; 

int sigvec ( 

int sig, 

struct sigvec *vec, 

struct sigvec *ovec 
); 

void (*signal(int sig, void (*func) (int) ) ) (int) ; 

DESCRIPTION 

These calls simulate (and are provided for backward compatibility with) functions of the same name in the 
4.2 Berkeley Software Distribution. 

This version of setpgrp ( ) is equivalent to the system call setpgid(pid,pgrp ) (see setpgid(2)). 

This version of getpgrp ( ) is equivalent to the system call getpgrp2 (pid ) (seegetpid(2)). 

ki llpg ( ) is equivalent to the system call ki 11 (-pgrp , sig ) (see kill(2)). 

sigvec ( ) is equivalent to the system call sigvector (sig, vec , ovec ) (see sigvector{2)), except for the 
following: 

When SIGCHLD or SIGCLD is used and vec specifies a catching function, the routine acts as if the 
SV_BSDSIG flag were included in the sv_f lags field of vec. 

The name sv_onstack can be used as a synonym for the name of the sv_f lags field of vec and 
ovec. 

If vec is not a null pointer and the value of (vec->sv_flags & 1) is "true", the routine acts as if the 
SV_ONSTACK flag were set. 

If ovec is not a null pointer, the flag word returned in ovec->sv_flags (and therefore the value of 
ovec->sv_onstack) will be equal to 1 if the system was reserving space for processing of that signal 
because of a call to sigspace(2), and if not. The SV_BSDSIG bit in the value placed in 
ovec->sv_flags is always clear. 

If the reception of a caught signal occurs during certain system calls, the call will always be restarted, 
regardless of the return value from a catching function installed with sigvec ( ) . The affected calls 
are wait(2), semop(2), msgsnd(2\ msgrcv{2), and read(2) or write(2) on a slow device (such as a termi- 
nal or pipe, but not a file). Other interrupted system calls are not restarted. 

This version of signal () has the same effect as sigvec(sig, vec, ovec), where vec->sv_handler is 
equal to func, vec->sv_mask is equal to 0, and vec->sv_flags is equal to 0. signal ( ) returns the value 
that would be stored in ovec->sv_handler if the equivalent sigvec ( ) call would have succeeded. Other- 
wise, signal ( ) returns -1 and errno is set to indicate the reason as it would have been set by the 
equivalent call to s igvec ( ) . 

These functions can be linked into a program by giving the - 1BSD option to ld(l). 

WARNINGS 

While the 4.3 BSD release defined extensions to some of the interfaces described here, only the 4.2 BSD 
interfaces are emulated by this package. 

bsdproc ( ) should not be used in conjunction with the facilities described under sigset(2V). 

AUTHOR 

bsdproc ( ) was developed by HP and the University of California, Berkeley. 
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SEE ALSO 

ld(l), kill(2), getpid(2), msgsnd(2), msgrcv(2), read(2), semop(2), setpgid(2), setsid(2), sigvector(2), wait(2), 

write(2), sigset(2V), sigstack(2), signal(5). ■ 
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NAME 

chdir, fchdir - change working directory 

SYNOPSIS 

#include <unistd.h> 

int chdir(const char *path) ; 
int fchdir(int fildes); 

DESCRIPTION 

chdir ( ) and fchdir ( ) cause a directory pointed to by path or fildes to become the current working 
directory, the starting point for path searches of path names not beginning with /. path points to the path 
name of a directory, fildes is an open file descriptor of a directory. 

For a directory to become the current working directory, a process must have execute (search) access to the 
directory. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

chdir ( ) fails and the current working directory remains unchanged if one or more of the following are 
true: 

[ENOTDIR] A component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for any component of the path name. 

[EFAULT] path points outside the allocated address space of the process. The reliable 

detection of this error is implementation dependent. 

[ENOENT] path is null. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length 

of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

fchdir ( ) fails and the current working directory remains unchanged if one or more of the following are 
true: 

[EACCES] Search permission is denied for fildes . 

[EBADF] fildes is not an open file descriptor. 

[ENOTDIR] The open file descriptor fildes does not refer to a directory. 

AUTHOR 

chdir () and fchdir () were developed by AT&T Bell Laboratories and HP. 

SEE ALSO 

cd(l), chroot(2). 

STANDARDS CONFORMANCE 

chdir ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

chmod, fchmod - change access mode of file 

SYNOPSIS 

ttinclude <sys/stat.h> 

int chmod (const char *path, mode_t mode) ; 
int fchmod ( int f i Ides , mode_t mode ) ; 

DESCRIPTION 

chmod ( } and fchmod { ) set the access permission portion of the file's mode according to the hit pattern 
contained in mode, path points to a path name naming a file, fildes is a file descriptor. 

The following symbolic constants representing the access permission bits are defined with the indicated 
values in <sys/stat .h> and are used to construct the mode argument. The value of mode is the bit-wise 
inclusive OR of the values for the desired permissions. 

S_ISUID 04000 Set user ID on execution. 

S_ISGID 02000 Set group ID on execution. 

S_ENPMT 02000 Record locking enforced. 

S_ISVTX oiooo Save text image after execution. 

S_IRUSR 00400 Read by owner. 

S_IWUSR 00200 Write by owner. 

S_IXUSR ooioo Execute (search) by owner. 

S_IRGRP 00040 Read by group. 

S_IWGRP 00020 Write by group. 

S_IXGRP oooio Execute (search) by group. 

S_IROTH 00004 Read by others (that is, anybody else). 

S_IW0TH 00002 Write by others. 

S_IX0TH ooooi Execute (search) by others. 

To change the mode of a file, the effective user ID of the process must match that of the owner of the file or a 
user with appropriate privileges. 

If the effective user ID of the process is not that of a user with appropriate privileges and the file is a regular 
file, S_ISVTX (mode bit 01000, save text image on execution) is cleared. 

If the effective user ID of the process is not that of a user with appropriate privileges, and the effective group 
ID of the process does not match the group ID of the file and none of the group ID s in the supplementary 
groups list match the group ID of the file, S_ISGIDR, S_ENPMT (mode bit 02000, set group ID on execu- 
tion and enforced file locking mode) is cleared. 

The set-group-ID on execution bit is also used to enforce file-locking mode (see lockf(2) and fcntl(2)) on files 
that are not group executable. This might affect future calls to open ( ) , creat ( ) , read ( ) , and 
write ( ) on such files (see open(2), creat(2\ read(2), and write(2)). 

If an executable file is prepared for sharing, S_ISVTX (mode bit 01000) prevents the system from aban- 
doning the swap-space image of the program-text portion of the file when its last user terminates. Then, 
when the next user of the file executes it, the text need not be read from the file system but can simply be 
swapped in, thus saving time. 

If mode S_ISVTX (mode bit 01000) is set on a directory, an unprivileged user cannot delete or rename oth- 
ers' files in that directory. 

Access Control Lists 

All optional entries in a file's access control fist are deleted when chmod ( ) is executed. (This behavior 
conforms to the IEEE Standard POSIX 1003.1-1988.) To preserve optional entries in a file's access control 
fist, it is necessary to save and restore them using getacl() and setacl() (see getacl(2) and 
setacl(2)). 

To set the permission bits of access control list entries, use setacl ( ) instead of chmod ( ) . 

For more information on access control fist entries, see acZ(5). 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is 
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set to indicate the error. 

ERRORS 

chmod ( ) and f chmod ( ) fail and the file mode is unchanged if one or more of the following is true: 

[EACCES] Search permission is denied on a component of the path prefix. 

[EFAULT] path points outside the allocated address space of the process. The reliable detection 

of this error is implementation dependent. 

[ELOOP] Too many symbolic links are encountered in translating path. 

[ENAMETOOLONG] 

A component of path exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in 
effect or path exceeds PATH_MAX bytes. 

[ENOENT] A component of path does not exist. 

[ENOENT] The file named by path does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The effective user ID does not match that of the owner of the file, and the effective 

user ID is not that of a user with appropriate privileges. 

[EROFS] The named file resides on a read-only file system. 

[EINVAL] Attempted to make a root directory into a context-dependent file (see DEPENDEN- 

CIES). 

WARNINGS 

Access Control Lists 

Access control list descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control fists are handled differently. Refer to HP-UX BLS documentation 
for information about access control fists in the HP-UX BLS environment. 

DEPENDENCIES 

HP Clustered Environment: 

If the file is a directory, the access permission bit S_CDP (04000) indicates a hidden directory 
(context-dependent file - see cdf(4)). A root directory cannot be made into a context-dependent file. 

NFS f chmod ( ) is not supported on remote files. 

AUTHOR 

chmod ( ) was developed by AT&T, the University of California, Berkeley, and HP. 

f chmod ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

chmod(l), chown(2), creat(2), fcntl(2), read(2), lockf(2), mknod(2), open(2), getacl(2), setacl(2), write(2), 
cdf(4), acl(5). 

STANDARDS CONFORMANCE 

chmod ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 

f chmod ( ) : AES 
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NAME 

chown, fchown - change owner and group of a file 

SYNOPSIS 

ttinclude <unistd.h> 

int chown(const char *path, uid_t owner, gid_t group); 
int fchown(int fildes, uid_t owner, gid_t group); 

DESCRIPTION 

chown ( ) changes the user and group ownership of a file, path points to a path name naming a file, fildes 
is a file descriptor, chown ( ) and fchown ( ) set the owner ID and group ID of the file to the numeric 
values contained in owner and group respectively. A value of UID_NO_CHANGE or GID_NO_CHANGE 
can be specified in owner or group to leave unchanged the file's owner ID or group ID respectively. Note that 
owner and group should be less than UID_MAX (see limits(5)). 

Only processes with effective user ID equal to the file owner or a user having appropriate privileges can 
change the ownership of a file. If privilege groups are supported, the owner of a file can change the owner- 
ship only if he is a member of a privilege group allowing CHOWN, as set up by the setprivgrp command 
(see setprivgrp(WL)). All users get CHOWN privileges by default. 

The group ownership of a file can be changed to any group in the current process's access list or to the real 
or effective group ID of the current process. If privilege groups are supported and the user is permitted the 
CHOWN privilege, the file can be given to any group. 

If chown ( ) is invoked on a regular file by other than the super-user the set-user-ID and set-group-ID bits 
of the file mode are cleared. Whether chown ( ) preserves or clears these bits on files of other types is 
implementation dependent. 

Access Control Lists (ACLs) 

A user can allow or deny specific individuals and groups access to a file by using the file's access control list 
(see ocZ(5)). When using chown() in conjunction with ACLs, if the new owner and/or group does not have an 
optional ACL entry corresponding to u .% and/or %.g in the file's access control list, the file's access permis- 
sion bits remain unchanged. However, if the new owner and/or group is already designated by an optional 
ACL entry of u . % and/or % .g, chown ( ) sets the file's permission bits (and the three basic ACL entries) to 
the permissions contained in that entry. 

ERRORS 

chown ( ) fails and the owner and group of the file remain unchanged if one or more of the following is true: 

[EBADF] fildes is not a valid file descriptor. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The file named by path does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID is not a user having appropriate privileges and one or more of the fol- 

lowing conditions exist: 

The effective user ID does not match the owner of the file. 

When changing the owner of the file, the owner of the file is not a member of a privilege 
group allowing the CHOWN privilege. 

When changing the group of the file, the owner of the file is not a member of a privilege 
group allowing the CHOWN privilege and the group number is not in the current process's 
access list. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path points outside the allocated address space of the process. The reliable detection of this 

error will be implementation dependent. 

[ENAMETOOLONG] 

A component oipath exceeds NAME_MAX bytes while _POSIX_NO_TRDNC is in effect, or 
path exceeds PATH_MAX bytes. 
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[ELOOP] Too many symbolic links were encountered in translating pat h. 

[EINVAL] Either owner or group is greater than or equal to UID_MAX. 

DEPENDENCIES 

Series 300, 400, and 700: 

If the path given to chown ( ) contains a symbolic link as the last element, this link is traversed and path- 
name resolution continues, chown ( ) changes the owner and group of the symbolic link's target, rather 
than the owner and group of the link. 

HP Clustered Environment: 

chown ( ) does not clear the set-user-ID bit of a directory because that bit indicates that the directory is 
hidden (see cdf(4)). 

When chown ( } is called from a cluster client node, the privilege groups checked are the ones set up 
on the cluster server. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and er rno is 
set to indicate the error. 

WARNINGS 

Access Control Lists 

Access control list descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

AUTHOR 

chown ( ) was developed by AT&T. 

f chown ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

chown(l), setprivgrp(lM), chmod(2), setacl(2), acl(5), limits(5), limits(5). 

STANDARDS CONFORMANCE 

chown ( ) : AES [Series 300/400/700 only], SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 

fchown():AES 
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NAME 

chroot - change root directory 

SYNOPSIS 

#include <unistd.h> 

int chroot (const char *path) ; 

DESCRIPTION 

chroot ( ) causes the named directory to become the root directory, the starting point for path searches for 
path names beginning with /. path points to a path name naming a directory. The user's working direc- 
tory is unaffected by the chroot ( ) system call. 

The effective user ID of the process must be a user having appropriate privileges to change the root direc- 
tory. 

The . . entry in the root directory is interpreted to mean the root directory itself. Thus, . . cannot be 
used to access files outside the subtree rooted at the root directory. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

chroot ( ) fails and the root directory remains unchanged if one or more of the following is true: 

[ENOTDIR] Any component of the path name is not a directory. 

[ENOENT] The named directory does not exist or a component of the path does not 

exist. 

[EPERM] The effective user ID is not a user who has appropriate privileges. 

[EFAULT] path points outside the allocated address space of the process. The reliable 

detection of this error is implementation dependent. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the 

length of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

SEE ALSO 

chroot(lM), chdir(2). 

STANDARDS CONFORMANCE 

chroot ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

close - close a file descriptor 

SYNOPSIS 

#include <unistd.h> 

int close (int fildes); 

DESCRIPTION 

close ( ) closes the file descriptor indicated by fildes. fildes is a file descriptor obtained from a creat ( ) , 
open ( ) , dup ( ) , f cnt 1 ( ) , or pipe ( ) system call. All associated file segments which have been locked 
by this process with the lockf ( ) function are released (i.e., unlocked). 

RETURN VALUE 

Upon successful completion, close ( } returns a value of 0; otherwise, it returns -1 and sets errno to 
indicate the error. 

ERRORS 

close ( ) fails if the any of following conditions are encountered: 

[EBADF] fildes is not a valid open file descriptor. 

[EINTR] An attempt to close a slow device or connection was interrupted by a signal. The file 

descriptor still points to an open device or connection. 

[ENOSPC] Not enough space on the file system. This error can occur when closing a file on an 

NFS file system. [When a write ( ) system call is executed on a local file system and 
if a new buffer needs to be allocated to hold the data, the buffer is mapped onto the 
disk at that time. A full disk is detected at this time and write ( ) returns an error. 
When the write ( ) system call is executed on an NFS file system, the new buffer is 
allocated without communicating with the NFS server to see if there is space for the 
buffer (to improve NFS performance). It is only when the buffer is written to the 
server (at file close or the buffer is full) that the disk-full condition is detected.] 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), lockff2), open(2), pipe(2). 

STANDARDS CONFORMANCE 

close ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

cnodeid - get the cnode ID of the local machine 

SYNOPSIS 

#include <cluster.h> 

cnode_t cnodeid (void) ; 

DESCRIPTION 

cnodeid ( ) returns the cnode ID of the local machine. 

SEE ALSO 

cnodes(l), cnodes(2), getcontext(2), getccent(3C). 

AUTHOR 

cnodeid was developed by HP. 



I 
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NAME 

cnodes - get a list of active nodes in cluster 

SYNOPSIS 

#include <cluster.h> 

int cnodes (cnode_t *buf); 

DESCRIPTION 

cnodes ( ) determines the number of active cnodes in the cluster, including the cnode on which it is 
invoked. If buf is not a null pointer, it must point to an array of type cnode_t with at least MAX_CNODE 
elements. In this case, the values of the cnode IDs of the nodes currently in the cluster are stored in the 
array, terminated by the cnode ID 0. 

RETURN VALUE 

Upon successful completion, cnodes ( ) returns the current number of active cnodes. If the value is 
returned, the machine is not a member of a cluster. In case of an error, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

cnodes ( ) may fail if: 

[EFAULT] buf is not a null pointer and points to an illegal address. Reliable detection of this 

error is not guaranteed. 

SEE ALSO 

cnodes(l), cnodeid(2), getcontext(2), getccent(3C). 

AUTHOR 

cnodes was developed by HP. 
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NAME 

connect - initiate a connection on a socket 

SYNOPSIS 

#include < sys/ socket .h> 

AFJNET only: 

# include <netinet/in.h> 

AFUNK only: 

Sine lu.de <sys/un*n> 

AP_CCITT only: 

ttinclude <x25/x25addrstr.h> 

lnt connect (lnt s, const void *addr, lnt addrlen) ; 

DESCRIPTION 

connect ( ) initiates a connection on a socket. 

The parameter s is a socket descriptor, addr is a pointer to a socket address structure containing the 
address of a remote socket to which a connection is to be established, addrlen is the size of this address 
structure. Since the size of the socket address structure varies among socket address families, the correct 
socket address structure should be used with each address family (for example, struct sockaddr_in 
for AF_INET, and struct sockaddr_un for AF_UNIX). Typically, the slzeof ( ) function is used 
to pass this value (for example, si zeof ( struct sockaddr_in) ). 

If the socket is of type SOCK_DGRAM, connect ( ) specifies the peer address to which messages are to be 
sent, and the call returns immediately. Furthermore, this socket can only receive messages sent from this 
address. 

If the socket is of type SOCK_STREAM, connect ( ) attempts to contact the remote host in order to make 
a connection between the remote socket (peer) and the local socket specified by s. The call normally blocks 
until the connection completes. If non-blocking mode has been enabled using the 0_NONBLOCK or 
OJNDELAY fcntlO flags or the FIOSNBIO ioctl() request and the connection cannot be com- 
pleted immediately, connect ( ) returns an error as described below. In these cases, select ( ) can be 
used on this socket to determine when the connection has completed by selecting it for writing. 

OJNONBLOCK and 0_NDELAY are denned in <sys/fcntl.h> and explained in fcnti(2), fcntl(5), and 
socket(7). FIOSNBIO is defined in <sys / ioct 1 . h> and explained in ioctl(2), ioctl(5), and socket(7). 

If s is a SOCK_STREAM socket that is bound to the same local address as another SOCK_STREAM socket, 
connect ( ) returns EADDRINUSE if addr is the same as the peer address of that other socket. This situa- 
tion can only happen if the SO_REUSEADDR option has been set on an AF_INET socket (see get- 
sockopt(2)). 

If the AFJNET socket does not already have a local name bound to it (see bind{2)\ connect ( ) also binds 
the socket to a local address chosen by the system. 

Generally, stream sockets may successfully connect only once; datagram sockets may use connect ( ) 
multiple times to change the peer address. For datagram sockets, a side effect of attempting to connect to 
some invalid address (see DIAGNOSTICS below) is that the peer address is no longer maintained by the sys- 
tem. An example of an invalid address for a datagram socket is addrlen set to and addr set to any value. 

AF_CCITT only: 

Use the x25addrstr struct for the address structure. The caller must know the X.121 address of the 
DTE to which the connection is to be established, including any sub-addresses or protocol-IDs that may be 
needed. Refer to af_ccitt(7F) for a detailed description of the x2 5addrstr address structure. If address- 
matching by protocol-ID, specify the protocol-ID with the X2 5_WR_USER_DATA ioctl () call before 
issuingthe connect () call. The X25_WR_USER_DATA ioctl () call is described in socketx25(7). 

DEPENDENCIES 
AF.CCITT: 

The SO_REUSEADDR option to setsockopt ( ) is not supported for sockets in the AF_CCITT address 
family. 
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RETURN VALUE 

Upon successful completion, connect ( ) returns 0; otherwise it returns -1 and sets errno to indicate 
the error. 

DIAGNOSTICS 

connect ( ) fails if any of the following conditions are encountered: 



[EBADF] 

[ENOTSOCK] 

[EADDRNOTAVAIL] 



[EAFNOSUPPORT] 



[EALREADY] 



[EISCONN] 
[EINVAL] 



[ETIMEDOUT] 

[ECONNREFUSED] 
[ENETUNREACH] 



[EADDRINUSE] 



[EFAULT] 
[EINPROGRESS] 



[ENODEV] 
[ENOSPC] 
[ENETDOWN] 



[ENOBUFSJ 



s is not a valid file descriptor. 

s is a file descriptor for a file, not a socket. 

The specified address is not available on this machine, or the socket is a 
TCP or UDP socket and the zero port number is specified. 

For datagram sockets, the peer address is no longer maintained by the sys- 
tem. 

Addresses in the specified address family cannot be used with this socket. 

For datagram sockets, the peer address is no longer maintained by the sys- 
tem. 

Non-blocking I/O is enabled using 0_NONBLOCK, 0_NDELAY, or 
PIOSNBIO, and a previous connection attempt has not yet completed. 

The socket is already connected. 

The socket has already been shut down, or has a listen ( ) active on it; 
addrlen is a bad value; an attempt was made to connect ( ) an AF_UNDC 
socket to an NFS-mounted (remote) name; the X.121 address length is zero, 
negative, or greater than fifteen digits. 

For datagram sockets, if addrlen is a bad value, the peer address is no 
longer maintained by the system. 

Connection establishment timed out without establishing a connection. 
backlog may be full (see listen{2)). 

The attempt to connect was forcefully rejected. 

The network is not reachable from this host. 

For AFCCnT only: X.25 Level 2 is down. The X.25 link is not working: 
wires might be broken, or connections are loose on the interface hoods at 
the modem, or the modem failed, or noise interfered with the line for an 
extremely long period of time. 

The address is already in use. 

For datagram sockets, the peer address is no longer maintained by the sys- 
tem. 

addr is not a valid pointer. 

Non-blocking I/O is enabled using 0_NONBLOCK, 0_NDELAY, or 
FIOSNBIO, and the connection cannot be completed immediately. This is 
not a failure. Make the connect ( ) call again a few seconds later. 
Alternatively, wait for completion by calling select (), selecting for 
write. 

The x25ifhame field refers to a non-existent interface. 

All available virtual circuits are in use. 

The X.25 interface specified in the addr struct was found or but was not in 
the initialized state. x25ifname field name is an interface which has been 
shut down or never initialized or suffered a power failure which erased its 
state information. 

No buffer space is available. The connect ( ) has failed. 



28 



-2 



HP-UX Release 9.0: August 1992 



connect (2) 



connect (2) 



[EINTR] 



[EOPNOTSUPP] 



The connect was interrupted by delivery of a signal before the connect 
sequence was complete. The building of the connection still takes place, 
even though the user is not blocked on the connect ( ) call. 

A connect ( ) attempt was made on a socket type which does not sup- 
port this call. Under X.25 an attempt was made to issue a connect ( ) 
call on a listen ( ) socket. 



AUTHOR 

connect ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

accept(2), select(2), socket(2), getsockname(2), socket(7), socketx25(7), af_ccitt(7F). 
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NAME 

creat - create a new file or rewrite an existing one 

SYNOPSIS 

tt Include <fcntl.h> 

int creat (const char *path, mode_t mode); 

DESCRIPTION 

creat ( ) creates a new regular file or prepares to rewrite an existing file named by the path name pointed 
to hy path. 

If the file exists, its length is truncated to 0, and its mode and owner are unchanged. Otherwise, the file's 
owner ID is set to the effective user ID of the process. If the set-group-ID bit of the parent directory is set, 
the file's group ID is set to the group ID of the parent directory. Otherwise, the file's group ID is set to the 
process's effective group ID. The low-order 12 bits of the file mode are set to the value of mode modified as 
follows: 

• All bits set in the process's file mode creation mask are cleared (see umask(2)). 

• The "save text image after execution" bit of the mode is cleared (see chmod{2)). 

Upon successful completion, the file descriptor is returned and the file is open for writing (only), even if the 
mode does not permit writing. The file offset is set to the beginning of the file. The file descriptor is set to 
remain open across exec ( ) system calls (see fcntl(2)). No process can have more than OPEN_MAX files 
open simultaneously. This is discussed in open(2). A new file can be created with a mode that forbids writ- 
ing. 

Access Control Lists (ACLs) 

On systems that support access control lists, three base ACL entries are created corresponding to the file 
access permission bits. An existing file's access control list is unchanged by creat ( ) (see setacl(2\ 
chmod(2), and acl(5)). 

ERRORS 

creat ( ) fails if one or more of the following is true: 

[EACCES] Search permission is denied on a component of the path prefix. 

[EACCES] The file does not exist and the directory in which the file is to be created does not permit 

writing. 

[EACCES] The file exists and write permission is denied. 

[EAGAIN] The file exists, enforcement mode file and record locking is set and there are outstanding 

record locks on the file. 

[EDQUOT] User's disk quota block or inode limit has been reached for this file system. 

[EFAULT] path points outside the allocated address space of the process. The reliable detection of this 

error is implementation dependent. 

[EISDIR] The named file is an existing directory. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[EMFILE] More than the maximum number of file descriptors are currently open. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a com- 
ponent of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in 
effect. 

[ENFILE] The system file table is full. 

[ENOENT] The named file does not exist (for example, path is null, or a component of path does not 

exist). 

[ENOSPC] Not enough space on the file system. 

[ENOTDIR] A component of the path prefix is not a directory. 
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[ENXIO] The named file is a character special or block special file, and the device associated with 

this special file does not exist. 

[EROFS] The named file resides or would reside on a read-only file system. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being executed. 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely the file descriptor, is returned. Otherwise, a 
value of -1 is returned and errno is set to indicate the error. 

Access Control Lists 

Access control fist descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control fists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), lockf(2), lseek(2), open(2), read(2), setacl(2), truncate(2), umask(2), 
write(2), acl(5). 

STANDARDS CONFORMANCE 

creat ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

dup - duplicate an open file descriptor 

SYNOPSIS 

ttinclude <unistd.h> 

int dup(int fildes); 

DESCRIPTION 

fildes is a file descriptor obtained from a creat ( ) , open ( ) , dup ( ) , f cnt 1 ( ) , or pipe ( ) system call, 
dup ( ) returns a new file descriptor having the following in common with the original: 

• Same open file (or pipe). 

• Same file pointer (i.e., both file descriptors share one file pointer). 

• Same access mode (read, write or read/write). 

• Same file status flags (see fcntl(2), P_DUPPD). 

The new file descriptor is set to remain open across exec ( ) system calls. See fcntl(2). 
The file descriptor returned is the lowest one available. 

RETURN VALUE 

Upon successful completion, the file descriptor is returned as a non-negative integer. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 

ERRORS 

dup ( ) fails if one or more of the following is true: 

[EBADF] fildes is not a valid open file descriptor. 

[EMFILE] Request violates the maximum number of open file descriptors. 

AUTHOR 

dup ( ) was developed by AT&T and HP. 

SEE ALSO 

close(2), creat(2), dup2(2), exec(2), fcntl(2), open(2), pipe(2). 

STANDARDS CONFORMANCE 

dup( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

dup2 - duplicate an open file descriptor to a specific slot 

SYNOPSIS 

#include <unistd.h> 

int dup2(int fildes, int fildes2); 

DESCRIPTION 

fildes is a file descriptor obtained from a creat ( ) , open ( ) , dup ( ) , f cntl ( ) , or pipe ( ) system call. 

fildes2 is a non-negative integer less than the maximum value allowed for file descriptors. 

dup2 ( ) causes fildes2 to refer to the same file as fildes. If fildes2 refers to an already open file, the open 
file is closed first. 

The file descriptor returned by dup2 ( ) has the following in common with fildes: 

• Same open file (or pipe). 

• Same file pointer (that is, both file descriptors share one file pointer.) 

• Same access mode (read, write or read/write). 

• Same file status flags (see fcntl(2), P_DUPPD). 

The new file descriptor is set to remain open across exec ( ) system calls. See fcnil(2). 

This routine is found in the C library. Programs using dup2 ( ) but not using other routines from the 
Berkeley importability library (such as the routines described in bsdproc(2)) should not give the -1BSD 
option to ld(l). 

RETURN VALUE 

Upon successful completion, dup2 () returns the new file descriptor as a non-negative integer, fildes2. 
Otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

dup2 ( ) fails if the following is true: 

[EBADF] fildes is not a valid open file descriptor or fildes2 is not in the range of legal file descriptors. 

[EINTR] An attempt to close fildes2 was interrupted by a signal. The file is still open. 

SEE ALSO 

close(2), creat(2), dup(2), exec(2), fcntl(2), open(2), pipe(2). 

STANDARDS CONFORMANCE 

dup2 ( ) : AES, SVID2, XPG3, XPG4, FIPS 151-2, POSDC.l 
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NAME 

errno - error indicator for function calls 

SYNOPSIS 

#include <errno.h> 

extern int errno; 

DESCRIPTION 

Many functions in the HP-UX operating system indicate an error condition by returning an otherwise out- 
of-range value (usually -1). Most of these functions set the external variable errno to a non-zero code 
value that more specifically identifies the particular error condition that was encountered. 

All errors detected and the corresponding error code values stored in errno are documented in the 
ERRORS section on manual pages for those functions that set it. 

The value of errno is zero immediately after a successful call to any of the functions described by exec(2) 
and ptrace(2), but it is never set to zero by any other HP-UX function. Functions for which the use of 
errno is not described may nevertheless change its value to a non-zero value. 

Since errno is not cleared on successful function calls, its value should be checked or used only when an 
error has been indicated and when the function's ERRORS section documents the error codes. 

Applications should not attempt to take the address of errno, because it may be converted to a macro in a 
future release. 

The following is a complete fist of the error codes. The numeric values can be found in <errno.h> but 
they should not be used in an application program because they can vary from system to system. 

E2BIG Arg list too long. An argument and or environment list longer than maximum supported 

size is presented to a member of the exec ( ) family. Other possibilities include: message 
size or number of semaphores exceeds system limit (msgop, semop), or too many 
privileged groups have been set up (setpr ivgrp). 

EACCES Permission denied. An attempt was made to access a file or IPC object in a way forbidden 

by the protection system. 

EADDRINUSE Address already in use. Only one usage of each address is normally permitted. 

EADDRNOTAVAIL 

Cannot assign requested address. Normally results from an attempt to create a socket 
with an address not on this machine. 

EAFNOSUPPORT 

Address family not supported by protocol family. An address incompatible with the 
requested protocol was used. For example, you should not necessarily expect to be able to 
use PUP Internet addresses with ARPA Internet protocols. 

EAGAIN No more processes. A fork ( ) failed because the system's process table is full or the user 

is not allowed to create any more processes, or a semop ( ) or msgop ( ) call would have 
to block. 

EALREADY Operation already in progress. An operation was attempted on a non-blocking object which 
already had an operation in progress. 

EBADF Bad file number. Either a file descriptor refers to no open file, a read (respectively write) 

request is made to a file which is open only for writing (respectively reading), or the file 
descriptor is not in the legal range of file descriptors. 

EBUSY Device or resource busy. An attempt to mount a device that was already mounted or an 

attempt was made to dismount a device on which there is an active file (open file, current 
directory, mounted-on file, active text segment). It will also occur if an attempt is made to 
enable accounting when it is already enabled. The device or resource is currently unavail- 
able, such as when a non-shareable device file is in use. 

ECHILD No child processes. A wait ( ) was executed by a process that had no existing or 

unwaited-for child processes. 
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ECONN ABORTED 



Software caused connection abort. A connection abort was caused internal to your host 
machine. 

ECONNREFUSED 

Connection refused. No connection could be made because the target machine actively 
refused it. This usually results from trying to connect to a service that is inactive on the 
foreign host. 

ECONNRESET Connection reset by peer. A connection was forcibly closed by a peer. This normally results 
from the peer executing a shutdown ( ) call (see shutdown®)). 

EDEADLK Resource deadlock would occur. A process which has locked a system resource would have 

been put to sleep while attempting to access another process' locked resource. 

EDESTADDRREQ 

Destination address required. A required address was omitted from an operation on a 
socket. 

EDOM Math argument. The argument of a function in the math package (3M) is out of the domain 

of the function. 

EEXIST File exists. An existing file was mentioned in an inappropriate context; e.g., 1 ink ( ) . 

EFAULT Bad address. The system encountered a hardware fault in attempting to use an argument 

of a system call; can also result from passing the wrong number of parameters to a system 
call. The reliable detection of this error is implementation dependent. 

EFBIG File too large. The size of a file exceeded the maximum file size (for the file system) or 

ULIMIT was exceeded (see ulimit(2)), or a bad semaphore number in a semop ( ) call (see 
semop(2)). 

EHOSTDOWN Host is down. A socket operation encountered a dead host. Networking activity on the 
local host has not been initiated. 

EHOSTUNREACH 

No route to host. A socket operation was attempted to an unreachable host. 

EIDRM Identifier Removed. This error is returned to processes that resume execution due to the 

removal of an identifier from the file system's name space (see msgctl(2), semctl{2), and 
shmctl(2)). 

EILSEQ Illegal byte sequence. A wide character code has been detected that does not correspond to 

a valid character, or a byte sequence does not form a valid wide character code. 

EINPROGRESS Operation now in progress. An operation that takes a long time to complete was attempted 
on a non-blocking object (see ioctl(2) and fcntl(2)). 

EINTR Interrupted system call. An asynchronous signal (such as interrupt or quit), which the user 

has elected to catch, occurred during a system call. If execution is resumed after processing 
the signal, it will appear as if the interrupted system call returned this error condition 
unless the system call is restarted (see sigvector(2)). 

EINVAL Invalid argument. Some invalid argument (such as unmounting a device that is not 

currently mounted, mentioning an undefined signal in signal ( ) or kill ( ) , or reading 
or writing a file for which lseek( ) has generated a negative pointer). Also set by the 
math functions described in the (3M) entries of this manual. 

EIO I/O error - some physical I/O error. This error may in some cases occur on a call following 

the one to which it actually applies. 

EISCONN Socket is already connected. A connect ( ) request was made on an already connected 

socket, or, a sendto ( ) or sendmsg ( ) request on a connected socket specified a desti- 
nation other than the connected party. 

EISDIR Is a directory. An attempt to open a directory for writing. 

ELOOP Too many levels of symbolic links. A path name search involved more than MAXSYM- 

LINKS symbolic links. MAXSYMLINKS is defined in <sys /par am . h>. 
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ENETDOWN 
ENETRESET 



ENETUNREACH 



EMFILE Too many open files. No process may have more than a system-defined number of file 

descriptors open at a time. 

EMLINK Too many links. An attempt to make more than the maximum number of links to a file. 

EMSGSIZE Message too long. The socket requires that the message be sent atomically, and the size of 

the message to be sent made this impossible. 

ENAMETOOLONG 

File name too long. A path specified exceeds the maximum path length for the system. The 
maximum path length is specified by PATH_MAX and is defined in <limits.h>. 
PATH_MAX is guaranteed to be at least 1023 bytes. This error is also generated if the 
length of a path name component exceeds NAME_MAX and the _POSIX_NO_TRUNC 
option is in effect for the specified path. Currently, _POSIX_NO_TRUNC is in effect only 
for HFS file systems configured to allow path name components up to 255 bytes long (see 
convertfs(lM)) and therefore only path names referring to such file systems can generate 
the error for this case. The values of NAME_MAX, PATH_MAX, and _POSIX_NO_TRUNC 
for a particular path name can be queried by using the pathconf ( ) system call (see 
pathconf(2)). 

Network is down. A socket operation encountered a dead network. 

Network dropped connection on reset. The host you were connected to crashed and 
rebooted. 

Network is unreachable. A socket operation was attempted to an unreachable network. 

File table overflow. The system's table of open files is full, and temporarily no more 
open ( ) s can be accepted. 

No buffer space available. An operation on a socket was not performed because the system 
lacked sufficient buffer space. 

No such device. An attempt was made to apply an inappropriate system call to a device 
(such as read a write-only device). 

No such file or directory. This error occurs when a file name is specified and the file should 
exist but does not, or when one of the directories in a path name does not exist. It also 
occurs with msgget ( ) , semget(), and shmget () when key does not refer to any 
object and the IPC_CREAT flag is not set. 

Exec format error. A request is made to execute a file which, although it has the appropri- 
ate permissions, does not start with a valid magic number (see a.out{A)), or the file is too 
small to have a valid executable file header. 

System lock table is full. Too many files have file locks on them, or there are too many 
record locks on files, or there are too many instances of a reading or writing process sleep- 
ing until an enforcement mode lock clears. This error may also indicate system problems in 
handling a lock request on a remote NFS file. This error is also currently returned for all 
attempts to perform locking operations on a remote NFS file that has its locking enforce- 
ment mode bit set, since the stateless nature of NFS prevents maintaining the necessary 
lock information. 

Not enough space. During a system call such as exec ( ) , brk ( ) , fork ( ) , or sbrk ( ) , a 
program asks for more space than the system is able to supply. This may not be a tem- 
porary condition; the maximum space size is a system parameter. The error can also occur 
if the arrangement of text, data, and stack segments requires too many segmentation regis- 
ters, or if there is not enough swap space during a fork ( ) . 

No message of desired type. An attempt was made to receive a message of a type that does 
not exist on the specified message queue; see msgop(2). 

ENOPROTOOPT Protocol not available. A bad option was specified in a getsockopt() or set- 
sockopt() call (see getsockopt (2)). 



ENFILE 



ENOBUFS 



ENODEV 



ENOENT 



ENOEXEC 



ENOLCK 



ENOMEM 
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ENOSPC No space left on device. During a write ( ) to an ordinary file, there is no free space left 

on the device; or no space in system table during msgget ( ) , semget ( ) , or semop ( ) 
while SEM_UNDO flag is set. 

ENOSYM Symbol does not exist in executable. The dynamic loader was unable to resolve a symbolic 

reference in a shared library during a call to one of the dynamic loader interface routines 
(see shl_load(SX). The program may be in an inconsistent state and should be terminated 
immediately. 

ENOSYS Function is not available. The requested function or operation is not implemented or not 

configured in the system. 

ENOTBLK Block device required. A non-block file was mentioned where a block device was required, 

such as in mount ( ) . 

ENOTCONN Socket is not connected. A request to send or receive data was disallowed because the 
socket was not connected. 

ENOTDIR Not a directory. A non-directory was specified where a directory is required, such as in a 

path prefix or as an argument to chdir ( ) . 

ENOTEMPTY Directory not empty. An attempt was made to remove a non-empty directory. 

ENOTSOCK Socket operation on non-socket. An operation was attempted on something that is not a 
socket. 

ENOTTY Not a typewriter. The (ioct 1 ( ) ) command is inappropriate to the selected device type. 

ENXIO No such device or address. I/O on a special file refers to a subdevice that does not exist, or 

is beyond the limits of the device. It can also occur when, for example, a tape drive is not 
on line or no disk pack is loaded on a drive. 

EOPNOTSUPP Operation not supported. The requested operation on a socket or NFS file is either invalid 
or unsupported. For example, this might occur when an attempt to accept ( ) a connec- 
tion on a datagram socket fails. 

EPERM Not owner. Typically, this error indicates an attempt to modify a file in some way forbid- 

den except to its owner or the super-user, such as to change its mode. It is also returned for 
attempts by ordinary users to do things for which they need, but lack, a special privilege. 

EPFNOSUPPORT 

Protocol family not supported. The protocol family has not been configured into the system 
or no implementation for it exists. The socket is not connected. 

EPIPE Broken pipe. Data has been written to a pipe for which the other (reading) end has been 

closed. This most often occurs when the reading process exits before the writing process. 
This condition also generates the signal SIGPIPE; the error is returned if the signal is 
ignored. 

EPROTONOSUPPORT 

Protocol not supported. The protocol has not been configured into the system or no imple- 
mentation for it exists. 

EPROTOTYPE Protocol wrong type for socket. A protocol was specified that does not support the seman- 
tics of the socket type requested. For example, ARPA Internet UDP protocol cannot be used 
with type SOCK_STREAM. 

Result too large. The value of a function in the math package (3M) is not representable 
within machine precision, or a semop ( ) call would cause either a semaphore value or a 
semaphore adjust value to exceed it system-imposed maximum. 

Read-only file system. An attempt to modify a file or directory was made on a device 
mounted read-only. 

Cannot send after socket shutdown. A request to send data was disallowed because the 
socket had already been shut down with a previous shutdown ( ) call. 

ESOCKTNOSUPPORT 

Socket type not supported. The support for the socket type has not been configured into the 
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ESPIPE 
ESRCH 

ETIMEDOUT 
ETXTBSY 



system or no implementation for it exists. 

Illegal seek. An lseek() was issued to a pipe. 

No such process. No process can be found corresponding to that specified by pid in 
ki 11 ( ) , rtprlo ( ) , or ptrace ( ) , or the process is not accessible. 

Connection timed out. A connect ( ) request failed because the connected party did not 
properly respond after a period of time (timeout period varies, depending on the communi- 
cation protocol). 

Text file busy. An attempt to execute an executable file which is currently open for writing 
(or reading). Also, an attempt to open for writing an otherwise writable file which is 
currently open for execution. 

EWOULDBLOCK 

Operation would block. An operation which would cause a process to block was attempted 
on an object in non-blocking mode (see ioctl(2) and fcntl(2)). 

EXDEV Cross-device link. A link to a file on another device was attempted. 

DEPENDENCIES 

The following NFS errors are also defined: 

EREFUSED The same error as ECONNREFUSED. The external variable errno is defined as ECONNRE- 
FUSED for NFS compatibility. 

EREMOTE Too many levels of remote in path. An attempt was made to remotely mount an NFS file 

system into a path which already has a remotely mounted NFS file system component. 

ESTALE Stale NFS file handle. A client referenced an open file, but the file was previously deleted. 

Series 700/800: 

In the definition of error ENOMEM, the term "segmentation registers" is invalid. 

STANDARDS CONFORMANCE 

errno: AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
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NAME 

execl, execv, execle, execve, execlp, execvp - execute a file 

SYNOPSIS 

#include <unistd.h> 

extern char **environ; 

int execl ( 

const char *path, 
const char *argO, ... 
/* const char *argl, 

• ♦ ♦ i 

const char *argn, 
(char *)0 */ 
); 

int execv (const char *path, char * const argv[]); 

int execle ( 

const char *path, 
const char *argO, ... 
/* const char *argl, 

• • • / 

const char *argn, 
(char *)0, 

char * const envpt] */ 
); 

int execve (const char *file, char * const argv[], char * const envp[]); 

int execlp ( 

const char *file, 
const char *argO, ... 
/* const char *argl, 
... / 

const char *argn, 
(char *)0 */ 
); 

int execvp (const char *file, char * const argv[]); 

DESCRIPTION 

exec ( ) , in all its forms, loads a program from an ordinary, executable file onto the current process, replac- 
ing the current program. The path or file argument refers to either an executable object file or a file of data 
for an interpreter. In this case, the file of data is also called a script file. 

An executable object file consists of a header (see a.out (4)), text segment, and data segment. The data seg- 
ment contains an initialized portion and an uninitialized portion (bss). For execlp ( ) and execvp ( ) 
the shell (/bin/sh) can be loaded to interpret a script instead. A successful call to exec ( ) does not return 
because the new program overwrites the calling program. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 

int argc; 

char **argv, **envp; 

where argc is the argument count and argv is the address of an array of character pointers to the argu- 
ments themselves. As indicated, argc usually has a value of at least one, and the first member of the array 
points to a string containing the name of the file. (Exit conditions from main are discussed in exit(2).) 

path points to a path name that identifies the executable file containing the new program. 

file (in execlp ( ) or execvp ( )) points to a file name identifying the executable file containing the new 
program. The path prefix for this file is obtained by searching the directories passed as the environment 
line PATH = (see environ^)). The environment is supplied by the shell (see sh(l)). If file does not have an 
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executable magic number (magic(4)\ it is passed to /bin/sh as a shell script. 

argO, argl, ..., argn are pointers to null-terminated character strings. These strings constitute the argu- 
ment list available to the new program. By convention, at least argO must be present and point to a string 
identical to path or path's last component. 

argv is an array of character pointers to null-terminated strings. These strings constitute the argument list 
available to the new program. By convention, argv must have at least one member, and must point to a 
string that is identical to path or path's last component, argv is terminated by a null pointer. 

envp is an array of character pointers to null-terminated strings. These strings constitute the environment 
in which the new program runs, envp is terminated by a null pointer. For exec ( ) and execv ( ) , the C 
run-time start-off routine places a pointer to the environment of the calling program in the global cell: 

cXbCXU C1J.O.J. "CUVJ.1UU/ 

and it is used to pass the environment of the calling program to the new program. 

Open file descriptors remain open, except for those whose close-on-exec flag is set (see fcntl(2)). The file 
offset, access mode, and status flags of open file descriptors are unchanged. 

Note that normal executable files are open only briefly when they start execution. Other executable file 
types can be kept open for a long time, or even indefinitely under some circumstances. 

The processing of signals by the process is unchanged by exec ( ) , except that signals caught by the pro- 
cess are set to their default value (see signal{2)). 

If the set-user-ID mode bit of the executable file pointed to by path or file is set (see chmod(2)), exec ( ) 
sets the effective-user-ID of the new process to the user ID of the executable file. Similarly, if the set-group- 
ID mode bit of the executable file is set, the effective-group-ID of the process is set to the group ID of the exe- 
cutable file. The real-user-ID and real-group-ID of the process are unchanged. Note that the set- 
user(group)-ID function does not apply to scripts; thus, if execlp ( ) or execvp ( ) executes a script, the 
set-user(group)-ID bits are ignored, even if they are set. 

The saved-user-ID and saved-group-ID of the process are always set to the effective-user-ID and effective- 
group-ID, respectively, of the process at the end of the exec, whether or not set-user(group)- ID is in effect. 

The shared memory segments attached to the calling program are not attached to the new program (see 
shmop(2j). 

Text and data segment memory locks are not passed on to the new program (see plock(2)). 

Profiling is disabled for the new process; see profil(2). 

The process also retains the following attributes: 

current working directory 

file creation mode mask (see umask(2)) 

file locks (see fcntl{2)\ except for files closed-on-exec 

file size limit (see ulimit(2)) 

interval timers (see getitimer(2)) 

nice value (see nice(2)) 

nice value (see parent process ID 

pending signals 

process ID 

process group ID 

real user ID 

real group ID 

real-time priority (see rtprio(2)) 

root directory (see chroot(2)) 

semadj values (see semop(2)) 

session membership 

signal mask (see sigvector(2)) 

supplementary group IDs 

time left until an alarm clock signal (see alarm(2)) 

trace flag (see ptrace(2) PT.SETTRC request) 
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• tms_utime, tms_stime, tms_cutime, and tms_cstime (see times(2)) 

The initial line of a script file must begin with # ! as the first two bytes, followed by zero or more spaces, 
followed by interpreter or interpreter argument. One or more spaces or tabs must separate interpreter and 
argument. The first line should end with either a new-line or null character. 

#1 interpreter 

#1 interpreter argument 

When the script file is executed, the system executes the specified interpreter as an executable object file. 
Even in the case of execlp ( ) or execvp ( ) , no path searching is done of the interpreter name. 

The argument is anything that follows the interpreter and tabs or spaces. If an argument is given, it is 
passed to the interpreter as argv [ 1 ] , and the name of the script file is passed as ar gv [ 2 ] . Otherwise, 
the name of the script file is passed as argv [1 ] . The argv [ ] is passed as specified in the exec ( ) 
call, unless either argv or argv [ ] is null as specified, in which case a pointer to a null string is passed 
as argv [ ] . All other arguments specified in the exec ( ) call are passed following the name of the 
script file (that is, beginning at argv [ 3 ] if there is an argument; otherwise at argv [ 2 ] ). 

If the initial line of the script file exceeds a system-defined maximum number of characters, exec ( ) fails. 
The minimum value for this limit is 32. 

Set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. 

RETURN VALUE 

If exec ( ) returns to the calling program, an error has occurred; the return value is -1 and errno is set 
to indicate the error. 

ERRORS 

exec ( ) fails and returns to the calling program if one or more of the following is true: 

[E2BIG] The number of bytes in the new program's argument list is greater than the system- 

imposed limit. This limit is at least 5120 bytes on HP-UX systems. 

[EACCES] Read permission is denied for the executable file or interpreter, and trace flag (see ptrace(2) 

request PT_SETTRC) of the process is set. 

[EACCES] Search permission is denied for a directory fisted in the executable file's or the interpreter's 

path prefix. 

[EACCES] The executable file or the interpreter is not an ordinary file. 

[EACCES] The file described by path or file is not executable. The super-user cannot execute a file 

unless at least one access permission bit or entry in its access control list has an execute bit 
set. 

[EFAULT] path, argv, or envp point to an illegal address. The reliable detection of this error is imple- 

mentation dependent. 

[EFAULT] The executable file is shorter than indicated by the size values in its header, or is otherwise 

inconsistent. The reliable detection of this error is implementation dependent. 

[EINVAL] The executable file is incompatible with the architecture on which the exec ( ) has been 

performed, and is presumed to be for a different architecture. It is not guaranteed that 
every architecture's executable files will be recognized. 

[ELOOP] Too many symbolic finks are encountered in translating the path name. 

[ENAMETOOLONG] 

The executable file's path name or the interpreter's path name exceeds PATH_MAX bytes, 
or the length of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[ENOENT] path is null. 

[ENOENT] One or more components of the executable file's path name or the interpreter's path name 

does not exist. 

[ENOEXEC] The exec ( ) is not an execlp () or execvpO, and the executable file has the 
appropriate access permission, but there is neither a valid magic number nor the 
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characters # ! as the first two bytes of its initial line. 

[ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. 

[ENOMEM] The new process requires more memory than is available or allowed by the system-imposed 

maximum. 

[ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a 

directory. 

[ETXTBSY] The executable file is currently open for writing. 

WARNINGS 

Access Control Lists 

Access control list descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

DEPENDENCIES 

Series 700/800 

Unsharable executable files (EXEC_MAGIC magic number produced via the -N option of ld(l)) are not 
supported. 

SEE ALSO 

sh(l), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), 
acl(5), environ(5), signal(5). 

STANDARDS CONFORMANCE 

environ: AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 

execl ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
execle ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l 
execlp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
execv( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
execve ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
execvp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

exit, _exit - terminate process 

SYNOPSIS 

ttinclude <stdlib.h> 

void exit(int status); 
#include <unistd.h> 
void _exit(int status); 

DESCRIPTION 

exit ( ) terminates the calling process and passes status to the system for inspection, see wait(2). Return- 
ing from main in a C program has the same effect as exit ( ) ; the status value is the function value 
returned by main (this value is undefined if main does not take care to return a value or to call exit ( ) 
explicitly). 

exit ( ) cannot return to its caller. The result of an exit ( ) call during exit processing is undefined. 

The functions exit ( ) and _exit ( ) , are equivalent, except that exit ( ) calls functions registered by 
atexit ( ) and flushes standard I/O buffers, while _exit ( ) does not. Both exit ( ) and _exit ( ) 
terminate the calling process with the following consequences: 

Functions registered by atexit ( ) (see atexit(2)) are called in reverse order of registration. 

All file descriptors open in the calling process are closed. 

All files created by tmpf i le ( ) are removed (see tmpfile(3S)). 

If the parent process of the calling process is executing a wait ( ) , wait3 ( ) , or waitpid ( ) , it is 
notified of the calling process's termination, and the low-order eight bits; i.e., bits 0377 of status are 
made available to it (see wait(2)). 

If the parent process of the calling process is not executing a wait ( ) , wait 3 ( ) , or waitpid ( ) , 
and does not have SIOCLD set to SIG_IGN, the calling process is transformed into a zombie pro- 
cess. A zombie process is a process that only occupies a slot in the process table. It has no other 
space allocated either in user or kernel space. Time accounting information is recorded for use by 
times ( ) (see times(2)). 

The parent process ID is set to 1 for all of the calling process's existing child processes and zombie 
processes. This means the initialization process (procl) inherits each of these processes. 

Each attached shared memory segment is detached and the value of shm_jnattach in the data 
structure associated with its shared memory identifier is decremented by 1 (see shmop(2)). 

For each semaphore for which the calling process has set a semadj value (see semop(2)), that semadj 
value is added to the semval of the specified semaphore. 

If the process has a process, text, or data lock, an unlock ( ) is performed, see plock{2). 

An accounting record is written on the accounting file if the system's accounting routine is enabled 
(see acct (2)). 

A SIGCHLD signal is sent to the parent process. 

If the calling process is a controlling process, the SIGHUP signal is sent to each process in the fore- 
ground process group of the controlling terminal belonging to the calling process. The controlling ter- 
minal associated with the session is disassociated from the session, allowing it to be acquired by a 
new controlling process. 

If the exit of the calling process causes a process group to become orphaned, and if any member of the 
newly-orphaned process group is stopped, all processes in the newly-orphaned process group are sent 
SIGHUP and SIGCONT signals. 

If the current process has any child processes that are being traced, they are sent a SIGKILL signal. 

AUTHOR 

exit ( ) was developed by HP, AT&T, and the University of California, Berkeley. 
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SEE ALSO 

Exit conditions ($?) in sh(l), 

acct(2), plock(2), semop(2), shmop(2), times(2), vfork(2), wait(2), signal(5). 

STANDARDS CONFORMANCE 

exit ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

_exlt ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

fcntl - file control 

SYNOPSIS 

# include <fcntl.h> 

int fcntl(int fildes, int cmd, /* arg */); 

DESCRIPTION 

fcntl ( ) provides for control over open files, fildes is an open file descriptor. 

The following are possible values for the cmd argument: 

P_DUPPD Return a new file descriptor having the following characteristics: 

• Lowest numbered available file descriptor greater than or equal to arg. val. 

• Same open file (or pipe) as the original file. 

• Same file pointer as the original file (that is, both file descriptors share one 
file pointer). 

• Same access mode (read, write or read/write). 

• Same file status flags (that is, both file descriptors share the same file status 
flags). 

• The close-on-exec flag associated with the new file descriptor is set to remain 
open across exec(2) system calls. 

Get the close-on-exec flag associated with the file descriptor fildes. If the low-order bit 
is the file will remain open across exec(2), otherwise the file will be closed upon exe- 
cution of exec (2). 

Set the close-on-exec flag associated with fildes to the low-order bit of arg. val (see 
P_6ETPD). 



P_6ETPD 

F_SETFD 

P_GETPL 
P_SETPL 

P GETLK 



Get file status flags and access modes; see fcntl(5). 

Set file status flags to arg . val. Only certain flags can be set; see fcntl(5). It is not 
possible to set both 0_NDELAY and 0_NONBLOCK. 

Get the first lock that blocks the lock described by the variable of type struct 
flock pointed to by arg. The information retrieved overwrites the information 
passed to fcntl ( ) in the flock structure. If no lock is found that would prevent 
this lock from being created, the structure is passed back unchanged, except that the 
lock type is set to P_UNLCK . 

Set or clear a file segment lock according to the variable of type struct flock 
pointed to by arg .lockdes (see fcntl(5)). The cmd P_SETLK is used to establish read 
(F_RDLCK) and write (P_WRLCK) locks, as well as to remove either type of lock 
(P_UNLCK). If a read or write lock cannot be set, fcntl ( ) returns immediately 
with an error value of — 1. 

This cmd is the same as F_SETLK except that if a read or write lock is blocked by 
other locks, the process will sleep until the segment is free to be locked. 

A read lock prevents any other process from write-lockmg the protected area. More than one read lock 
can exist for a given segment of a file at a given time. The file descriptor on which a read lock is being 
placed must have been opened with read access. 

A write lock prevents any other process from read-locking or write-locking the protected area. Only 
one write lock may exist for a given segment of a file at a given time. The file descriptor on which a 
write lock is being placed must have been opened with write access. 

The structure flock describes the type (l_type), starting offset (l_whence), relative offset 
(l_start), size (l_len), and process ID (l_pld) of the segment of the file to be affected. The pro- 
cess ID field is only used with the F_GETLK cmd to return the value of a block in lock. Locks can 
start and extend beyond the current end of a file, but cannot be negative relative to the beginning of 
the file. A lock can be set to always extend to the end of file by setting l_len to zero (0). If such a 
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lock also has l_start set to zero (0), the whole file will be locked. Changing or unlocking a segment 
from the middle of a larger locked segment leaves two smaller segments for either end. Locking a seg- 
ment already locked by the calling process causes the old lock type to be removed and the new lock 
type to take effect. All locks associated with a file for a given process are removed when a file descrip- 
tor for that file is closed by that process or the process holding that file descriptor terminates. Locks 
are not inherited by a child process in a fork{2) system call. 

When enforcement-mode file and record locking is activated on a file (see chmod(2)\ future read ( ) 
and write ( ) system calls on the file are affected by the record locks in effect. 

NETWORKING FEATURES 

NFS The advisory record-locking capabilities of fcntl(2) are implemented throughout the network by the 
"network lock daemon" (see lockd(lM)). If the file server crashes and is rebooted, the lock daemon 
attempts to recover all locks associated with the crashed server. If a lock cannot be reclaimed, the pro- 
cess that held the lock is issued a SIGLOST signal. 

Record locking, as implemented for NFS files, is only advisory. 

RETURN VALUE 

Upon successful completion, the value returned depends on cmd as follows: 

F_DUPFD A new file descriptor. 

F_GETFD Value of close-on-exec flag (only the low-order bit is defined). 

F_SETFD Value other than -1. 

F_GETFL Value of file status flags and access modes. 

F_SETFL Value other than -1. 

F_GETLK Value other than -1. 

F_SE TLK Value other than -1 . 

F_SETLKW Value other than -1. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

f cntl ( ) fails if any of the following conditions occur: 

[EBADF] fildes is not a valid open file descriptor, or was not opened for reading when setting a 

read lock or for writing when setting a write lock. 

[EMFILE] cmd is F_DUPFD and the maximum number of file descriptors is currently open. 

[EMFILE] cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and no more 

file-locking headers are available (too many files have segments locked). 

[EMFILE] cmd is F_DUPFD and arg . vol is greater than or equal to the maximum number of 

file descriptors. 

[EMFILE] cmd is F_DUPFD and arg . vol is negative. 

[EINVAL] cmd is F_GETLK, F_SETLK, or F_SETLKW, and arg .lockdes or the data it points to 

is not valid, or fildes refers to a file that does not support locking. 

[EINVAL] cmd is not a valid command. 

[EINVAL] cmd is F_SETFL and both 0_NONBLOCK and 0_NDELAY are specified. 

[EINTR] cmd is F_SETLKW and the call was interrupted by a signal. 

[EACCES] cmd is F_SETLK, the type of lock (l_type) is a read lock ( F_RDLCK) or write lock 

(FJWRLCK) and the segment of a file to be locked is already write-locked by another 
process, or the type is a write lock (F_WRLCK) and the segment of a file to be locked 
is already read- or write-locked by another process. 

[ENOLCK] cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and no more 

file-locking headers are available (too many files have segments locked), or no more 
record locks are available (too many file segments locked). 
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[ENOLCK] cmd is P_SETLK or P_SETLKW, the type of lock (l_type) is a read lock 

(F_RDLCK) or write lock (F_WRLCK) and the file is an NFS file with access bits set 
for enforcement mode. 

[ENOLCK] cmd is P_6ETLK, F_SETLK, or F_SETLKW, the file is an NFS file, and a system error 

occurred on the remote node. 

[EDEADLK] cmd is F_SETLKW, when the lock is blocked by a lock from another process and sleep- 
ing (waiting) for that lock to become free. This causes a deadlock situation. 

[EAGAIN] cmd is P_SETLK or F_SETLKW, and the file is mapped in to virtual memory via the 

mmapO system call (see mmap (2)). 

[EFAULT] cmd is either F_GETLK, F_SETLK, or F_SETLKW, and org points to an illegal 

address. 

AUTHOR 

f cnt 1 ( ) was developed by HP, AT&T and the University of California, Berkeley. 

APPLICATION USAGE 

Because in the future the external variable errno will be set to EAGAIN rather than EACCES when a sec- 
tion of a file is already locked by another process, portable application programs should expect and test for 
either value, for example: 

flk->l_type = F_RDLCK; 

if (fcntl(fd, f_setlk, flk) == -1) 

if ( (errno == eacces) I | (errno == eagain) ) 
/* 

* section locked by another process, 

* check for either EAGAIN or EACCES 

* due to different implementations 
*/ 

else if ... 
/* 

* check for other errors 
*/ 

SEE ALSO 

lockd(lM), statd(lM), chmod(2), close(2), exec(2), lockf(2), open(2), read(2), write(2), fcntl(5). 

FUTURE DIRECTIONS 

The error condition which currently sets errno to EACCES will instead set errno to EAGAIN (see also 
APPLICATION USAGE above). 

STANDARDS CONFORMANCE 

f cnt 1 ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

fork - create a new process 

SYNOPSIS 

#include <unistd.h> 

pid_t fork (void) ; 

DESCRIPTION 

f ork ( ) causes the creation of a new process. The new process (child process) is an exact copy of the cal- 
ling process (parent process). This means that the child process inherits the following attributes from the 
parent process: 

Real, effective, and saved user ID. • 

Real, effective, and saved group ID. 

List of supplementary group IDs (see getgroups(2)). 

Process group. ID 

Environment. 

File descriptors. 

Close-on-exec flags (see exec (2)). 

Signal handling settings (SIG_DPL, SIG_I6N, address). 

Signal mask (see sigvector(2)). 

Profiling on/off status (see profil(2)). 

Command name in the accounting record (see acct(4)). 

Nice value (see nice(2)). 

All attached shared memory segments (see shmop(2)). 

Current working directory 

Root directory (see chroot(2)). 

File mode creation mask (see umask(2)). 

File size limit (see ulimit(2)). 

Real-time priority (see rtprio(2)). 

Each of the child's file descriptors shares a common open file description with the corresponding file descrip- 
tor of the parent. This implies that changes to the file offset, file access mode, and file status flags of file 
descriptors in the parent also affect those in the child, and vice-versa. 

The child process differs from the parent process in the following ways: 

The child process has a unique process ID. The child process ID also does not match any active process 
group ID. 

The child process has a different parent process ID (which is the process ID of the parent process). 

The set of signals pending for the child process is initialized to the empty set. 

The trace flag (see ptrace(2) PT_SETTRC request) is cleared in the child process. 

The AFORK flag in the ac_f lags component of the accounting record is set in the child process. 

Process locks, text locks, and data locks are not inherited by the child (seeplock(2)). 

All semad j values are cleared (see semop(2J). 

The child process's values of tms_ut ime, tms_stime, tms_cutime, and tms_cstime are set 
to zero (see times(2)). 

The time left until an alarm clock signal is reset to (clearing any pending alarm), and all interval 
timers are set to (disabled). 

The vfork(2) system call can be used to fork processes more quickly than f ork( ), but has some restric-^ 
tions. See vfork(2) for details. 

If a parent and child process both have a file opened and the parent or child closes the file, the file is still 
open for the other process. 

RETURN VALUE 

Upon successful completion, f ork( ) returns a value of to the child process and returns the process ID 
of the child process to the parent process. Otherwise, a value of -1 is returned to the parent process, no 
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child process is created, and errno is set to indicate the error. 

The parent and child processes resume execution immediately after the fork() call; they are dis- 
tinguished by the value returned by fork . 

ERRORS 

fork ( ) fails and no child process is created if one or more of the following is true: 

[EAGAIN] The system-imposed limit on the total number of processes under execution would be 

exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes under execution by a sin- 

gle user would be exceeded. 

[ENOMEM] There is insufficient swap space and/or physical memory available in which to create 
the new process. 

WARNINGS 

Standard I/O streams (see stdio (3S)) are duplicated in the child. Therefore, if fork is called after a buffered 
I/O operation without first closing or flushing the associated standard I/O stream (see /b/ose(3S)), the 
buffered input or output might be duplicated. 

AUTHOR 

fork ( ) was developed by AT&T, the University of California, Berkeley, and HP. 

SEE ALSO 

acct(2), chroot(2), exec(2), exit(2), fcntl(2), getgroups(2), lockf(2), nice(2), plock(2), profil(2), ptrace(2), 
rtprio(2), semop(2), setuid(2), setpgrp(2), shmop(2), times(2), ulimit(2), umask(2), vfork(2), wait(2), 
fclose(3S), stdio(3S), acct(4), signal(5). 

STANDARDS CONFORMANCE 

fork ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 



HP-UX Release 9.0: August 1992 - 2 - 49 



I 



fsctl(2) fsctl(2) 



NAME 

fsctl - file system control 

SYNOPSIS 

#include <sys/f sctl.h> 

int fsctl ( 

int fildes, 

int command, 

void * outbuf, 

size_t outlen 
); 

DESCRIPTION 

f set i ( ) provides access to file-system-specific information, fildes is an open file descriptor for a file in the 
file system of interest. The possible values for command depend on the type of file system. Currently, 
defined commands exist only for the CDFS file system (see sys/cdf sdir .h). 

outbuf is a pointer to the data area in which data is returned from the file system, outlen gives the length 
of the data area pointed to by outbuf. 

The CDFS commands are: 

CDPS_DIR_REC Returns the directory record for the file or directory indicated by fildes. The record 
is returned in a structure of type eddir, defined in <sys/cdf sdir . h>. 

CDPS_XAR Returns the extended attribute record, if any, for the file or directory indicated by 

fildes. Because the size of an extended attribute record varies, be sure outbuf 
points to a data area of sufficient size. To find the necessary size, do the following: 

1. Use statfs(2). to get the logical block size of the CDFS volume. 

2. Use an fsctl () call with the CDPS_DIR_REC command to get the 
extended attribute record size (in blocks) for the file or directory of 
interest. The mincdd_xar_len field in the returned structure con- 
tains the size of the extended attribute record in logical blocks. (If this 
field is zero, the file or directory has no extended attribute record.) 

3. Multiply mincdd_xar_len by the logical block size obtained in step 
1 to get the total space needed. 

4. Once you get the extended attribute record, cast outbuf into a pointer to 
a structure of type cdxar_iso (defined in <sys/cdf sdir.h>). 
This enables you to access those fields that are common to all extended 
attribute records. (See EXAMPLES below for an example of this pro- 
cess.) 

If the extended attribute record contains additional system use or 
application use data, that data will have to be accessed manually. 

CDPS_APID Returns the abstract file identifier for the primary volume whose root directory is 

specified by fildes, terminated with a NULL character. Note that the constant 
CDMAXNAMLEN defined in <sys/cdf sdir .h> gives the maximum length a file 
identifier can have. Thus, CDMAXNAMLEN + 1 can be used for outlen and the size 
of outbuf. 

CDPS_BPID Returns the bibliographic file identifier for the primary volume whose root direc- 

tory is specified by fildes, terminated with a NULL character. CDMAXNAMLEN + 
1 can be used for the value of outlen and the size of outbuf. 

CDFS_CFID Returns the copyright file identifier for the primary volume whose root directory is 

specified by fildes, terminated with a NULL character. CDMAXNAMLEN + 1 can 
be used for the value of outlen and the size of outbuf. 

CDPS_VOL_ID Returns the volume ID for the primary volume specified by fildes, terminated with 
a NULL character. The maximum size of the volume ID is 32 bytes, so a length of 
33 can be used for outlen and the size of utbuf. 
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CDPS_VOL_SET_ID 

Returns the volume set ID for the primary volume specified by fildes, terminated 
with a NULL character. The maximum size of the volume set ID is 128 bytes, so a 
length of 129 can be used for outlen and the size of outbuf. 

EXAMPLES 

The following code fragment gets the extended attribute record for a file on a CDFS volume. The filename is 
passed in as the first argument to the routine. Note that error checking is omitted for brevity. 

ttinclude <sya/ types. h> 

tfinclude <sys/vfs.h> 

^include <fcntl.h> 

# include <sys/cdfsdir.h> 

main(argc, argv) 

lnt argc; 

char *argv [ ] ; 

{ 

lnt fildes, size = 0; 

char *malloc ( ) , * outbuf ; 

struct statfs buf; 

struct cddir cdrec; 

struct cdxar_iso *xar; 



statf s(argv[l] , &buf); /* get logical block size */ 

fildes = open (argv [1] , 0_RDONLY); /* open file arg */ 

/* get directory record for file arg */ 

fsctl (fildes, CDPS_DIR_REC, &cdrec, sizeof (cdrec) ) ; 

size as buf.f_bsize * cdrec. cdd_min.mincdd_xar_len; /* compute size */ 

if (size) { /* if size != then there is an xar */ y 

outbuf = malloc (size) ; /* malloc sufficient memory */ 

fsctl (fildes, CDFS_XAR, outbuf, size); /* get xar */ 

xar as (struct cdxar_iso *)outbuf; /* cast outbuf to access fields */ 
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} 

RETURN VALUE / 

fsctl ( ) returns the number of bytes read if successful. If an error occurs, -1 is returned and errno is 
set to indicate the error. 

ERRORS 

f set 1 ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid open file descriptor. 

[EFAULT] outbuf points to an invalid address. 

[ENOENT] The requested information does not exist. 
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[EINVAL] command is not a valid command. 

[EINVAL] outlen is negative, or fildes does not refer to a CDFS file system. 

SEE ALSO 

statfs(2), cdfs(4), cdfsdir(4), cdnode(4), cdrom(4). 
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NAME 

fsync - synchronize a file's in-core state with its state on disk 

SYNOPSIS 

ttinclude <unistd.h> 

int fsync (int fildes); 

DESCRIPTION 

fsync ( ) causes all modified data and attributes of fildes to be moved to a permanent storage device. This 

normally results in all in-core modified copies of buffers for the associated file to be written to a disk. 

fsync ( ) applies to ordinary files, and applies to block special devices on systems which permit I/O to block _ 

special devices. I 

fsync ( ) should be used by programs that require a file to be in a known state; such as when building a 
simple transaction facility. 

RETURN VALUE 

fsync ( ) returns on success or -1 if an error error occurs, and sets errno to indicate the error. 

ERRORS 

fsync fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid descriptor. 

[EINVAL] fildes refers to a file type to which fsync ( ) does not apply. 

WARNINGS 

The current implementation of this function is inefficient for large files. 

AUTHOR 

fsync ( ) was developed by the the University of California, Berkeley and HP. 

SEE ALSO 

fcntl(2), fcntl(5), open(2), select(2), sync(2), sync(lM). 

STANDARDS CONFORMANCE 

fsync ( ) : AES, XPG3, XPG4 
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NAME 

ftime - get date and time more precisely 

SYNOPSIS 

# include <sys/timeb.h> 

int ftime (struct timeb *tp); 

REMARKS 

This facility is provided for backwards compatibility with Version 7 systems. Either time ( ) or get- 
t imeof day ( ) should be used in new programs. 

DESCRIPTION 

ft ime ( ) fills in a structure pointed to by its argument, as defined by <sys / 1 imeb . h>: 

/* 
* Structure returned by ftime system call 
*/ 
struct timeb { 
time_t time; 
unsigned short millitm; 
short time zone; 
short dstflag; 
}; 

The structure contains the time in seconds since 00:00:00 UTC (Coordinated Universal Time), January 1, 
1970, up to 1000 milliseconds of more-precise interval, the local timezone (measured in minutes of time 
westward from UTC), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during 
the appropriate part of the year. Consult gettimeofday(2) for more details on the meaning of the timezone 
field. 

This function can be accessed by giving the - 1V7 option to the Id command (see ld(l)). 

ft ime ( ) can fail for exactly the same reasons as gettimeofday(2). 

SEE ALSO 

date(l), gettimeofday(2), stime(2), time(2), ctime(3C). 

WARNINGS 

The millisecond value usually has a granularity greater than one due to the resolution of the system clock. 
Depending on any granularity (particularly a granularity of one) renders code non-portable. 
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NAME 

getaccess - get a user's effective access rights to a file 

SYNOPSIS 

ttinclude <sys/getaccess.h> 

int getaccess ( 

const char *path, 

uid_t uid, 

int ng roups, 

const gid_t *gidset. 

void * label, 

void *privs 
); 

DESCRIPTION 

getaccess ( ) identifies the access rights (read, write, execute/search) a specific user ID has to an existing 
file, path points to a path name of a file. If the call succeeds, it returns a value of zero or greater, 
representing the specified user's effective access rights (modes) to the file. The rights are expressed as the 
logical OR of hits (R_OK, W_OK, and X_OK) whose values are defined in the header <unistd . h>. A return 
of zero means that access is denied. 

The uid parameter is a user ID. Special values, defined in <sys/getaccess.h>, represent the calling 
process's effective, real, or saved user ID: 

UID_EUID Effective user ID. 
UI D_RUID Real user ID. 
UID_SUID Saved user ID. 

ngroups is the number of group IDs iagidset, not to exceed NGROUPS_MAX + 1 (NGROUPS_MAX is defined 
in <limits .h>). If the ngroups parameter is positive, the gidset parameter is an array of group ID values 
to use in the check. If ngroups is a recognized negative value, gidset is ignored. Special negative values of 
ngroups, defined in <sys/ get access .h>, represent various combinations of the process's effective, real, 
or saved user ID and its supplementary groups fist: 

Use process's effective group ID only. 

Use process's real group ID only. 

Use process's saved group ID only. 

Use process's supplementary groups only. 

Use process's effective group ID plus supplementary groups. 

Use process's real group ID plus supplementary groups. 

Use process's saved group ID plus supplementary groups. 

The label and privs parameters are placeholders for future extensions. For now, the values of these param- 
eters must be (void *) 0. 

The access check rules for access control fists are described in acl(5). In addition, the W_OK bit is cleared 
for files on read-only file systems or shared-text programs being executed. Note that as in access(2), the 
X_OK bit is not turned off for shared-text programs open for writing because there is no easy way to know 
that a file open for writing is a shared-text program. 

If the caller's user ID is 0, or if it is UID_EUID, UID_RUID, or UID_SUID (see <sys/ getaccess .h>) 
and the process's respective user ID is 0, R_OK and W_OK are always set except when W_OK is cleared for 
files on read-only file systems or shared-text programs being executed. X_OK is set if and only if the file is 
not a regular file or the execute bit is set in any of the file's ACL entries. 

getaccess () checks each directory component of path by first using the caller's effective user ID, 
effective group ID, and supplementary groups list, regardless of the user ID specified. An error occurs, dis- 
tinct from "no access allowed," if the caller cannot search the path to the file. (In this case it is inappropri- 
ate for the caller to learn anything about the file.) 

Comparison of access(2) an.dgetaccess(2) 

The following table compares various attributes of access ( ) and getaccess ( ) . 
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NGROUPS 


EGID 




NGROUPS. 


_RGID 




NGROUPS 


SGID 




NGROUPS. 


SUPP 




NGROUPS 


EGID_ 


SUPP 


NGROUPS. 


_RGID_ 


.SUPP 


NGROUPS 


SGID 


SUPP 



getaccess(2) 



getaccess(2) 



access () 


getaccess () 


checks all AUL entries 


same 


uses real uid, real gid, and 
supplementary groups list 


uses specified uid and groups fist; 
macros available for typical values 


checks specific mode value, 
returns succeed or fail 


returns all mode bits, each on or off 


checks path to file using caller's effective IDs 


same 


W_OK false if shared-text file 
currently being executed 


same 


W_OK false if file on 
read-only file system 


same 


x_OK not modified for file 
currently open for writing 


same 


R_OK and W_OK always true for superuser 
(except as above) 


same 


X_OK always true for superuser 


X_OK true for super-user if file is not a regular 
file or execute is set in any ACL entry 



RETURN VALUE 

Upon successful completion, getaccess ( ) returns a non-negative value representing the access rights of 
the specified user to the specified file. If an error occurs, a value of -1 is returned and errno is set to 
indicate the error. 

ERRORS 

getaccess ( ) fails if any of the following conditions are encountered: 

[EACCES] A component of the path prefix denies search permission to the caller. 

[EFAULT] path or gidset points outside the allocated address space of the process. The reliable 

detection of this error is implementation dependent. 

[EINVAL] ngroups is invalid; ngroups is either zero, an unrecognized negative value, or a value 

larger than NGROUPS + 1. 

[EINVAL] gidset contains an invalid group ID value. 

[EINVAL] The value of label or privs is not a null pointer. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENOENT] The named file does not exist (for example, path is null or a component of path does 

not exist). 

[ENOTDIR] A component of the path prefix is not a directory. 

[EOPNOTSUPP] getaccess() is not supported on some types of remote files. 

EXAMPLES 

The following call determines the caller's effective access rights to file "test," and succeeds if the user has 
read access: 

ttinclude <unistd.h> 
ttinclude <sys/getaccess.h> 

int mode; 

mode = getaccess ("test", UID_EUID, NGR0UPS_E6ID_SUPP / 

(lnt *) 0, (void *) 0, (void *) 0); 

if ((mode >= 0) && (mode & R_OK) ) ... 

Here is one way to test access rights to file /tmp/hold for user ID 2 3, group ID 1 9 : 
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int gid = 109; 
int mode; 

mode = getaccess ( "/tmp/hold", 23, 1, & gid, 
(void *) 0, (void *) 0); 

Should the need arise, the following code builds a gidset that includes the process's effective group ID: 

#include <limits.h> 

int gidset [NGROUPS_MAX +1]; 
int ng tout's; 

gidset [0] = getegidO; 

ngroups = 1 + getgroups (NGROUPS_MAX, & gidset [1]); 

AUTHOR 

getaccess ( ) was developed by HP. 

SEE ALSO 

access(2), chmod(2), getacl(2), setacl(2), stat(2), acl(5), unistd(5). 
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NAME 

getacl, fgetacl - get access control list (ACL) information 

SYNOPSIS 

#include <sys/acl.h> 

Int getacl ( 

const char *path, 

int nentries, 

struct acl_entry *acl 
); 
Int fgetacl(int fildes, int nentries, struct acl_entry *acl) ; 

DESCRIPTION 

getacl ( ) returns a complete listing of all ACL entries {uid.gid, mode) in an existing file's access control 
list, path points to a path name of a file. 

Similarly, fgetacl ( ) returns a complete listing of all ACL entries for an open file known by the file 
descriptor fildes. 

nentries is the number of entries being reported on, and is never more than the constant NACLENTRIES 
defined in <sys/acl .h>. If nentries is non-zero, it must be at least as large as the number of entries in 
the file's ACL, including base entries (see setacl{2)). getacl ( ) returns the number of entries in the file's 
ACL, as well as the ACL entries themselves in the array of structures acl declared by the calling program. 

If nentries is zero, getacl ( ) returns the number of entries in the file's ACL, including base ACL entries, 
and acl is ignored. 

Entries are reported in groups of decreasing order of specificity (see setacl(2)), then sorted in each group by 
user ID and group ID. The content of array entries beyond the number of defined entries for the file is 
undefined. 

RETURN VALUE 

Upon successful completion, getacl () and fgetacl () return a non-negative value. If an error 
occurs, a value of -1 is returned, and errno is set to indicate the error. 

ERRORS 

getacl ( ) or fgetacl ( ) fail to modify the acl array if any of the following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist (for example, path is null or a component of path does 

not exist). 

[EBADF] fildes is not a valid file descriptor. 

[EACCES] A component of the path prefix denies search permission. 

[EFAULT] path or a portion of acl to be written points outside the allocated address space of the 

process. 

[EINVAL] nentries is non-zero and less than the number of entries in the file's ACL, or it is 

greater than NACLENTRIES. 

[EOPNOTSUPP] getacl ( ) is not supported on remote files by some networking services. 

[ENFILE] The system file table is full. 

[ENAMETOOLONG] 

The length of path exceeds PATHJMAX bytes, or the length of a component of path 
exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

EXAMPLES 

The following call returns the number of entries in the ACL on file /users/bill/mcf ile. 

#include <sys/acl.h> 
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entries = getacl ("/users/bill/mcf ile" # 0, (struct acl_entry *) 0); 

The following call returns in acl all entries in the ACL on the file opened with file descriptor 5. 

# include <sys/acl.h> 

int nentries; 

struct acl_entry acl [NACLENTRIES] ; 

entries = fgetacl (5, NACLENTRIES, acl); 

DEPENDENCIES 

NFS getacl ( ) and fgetacl ( ) are not supported on remote files. 

AUTHOR 

getacl ( ) and fgetacl ( ) were developed by HP. 

SEE ALSO 

access(2), chmod(2), getaccess(2), setacl(2), stat(2), unistd(5). 
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NAME 

getaudid - get the audit ID (aid) for the current process 

SYNOPSIS 

#include <sys/audit.h> 

int getaudid (void) ; 

DESCRIPTION 

getaudid ( ) returns the audit ID (aid ) for the current process. This call is restricted to the super-user. 

RETURN VALUE 

Upon successful completion, the audit ID is returned; otherwise, a - 1 is returned. 

ERRORS 

getaudid ( ) fails if the following is true: 

[EPERM] The caller is not super-user. 

AUTHOR 

getaudid ( ) was developed by HP. 

SEE ALSO 

setaudid(2). 
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NAME 

getaudproc - get the audit process flag for the calling process 

SYNOPSIS 

# include < ays/ audi t.h> 

int getaudproc (void) ; 

DESCRIPTION 

getaudproc ( ) returns the audit process flag for the calling process. The audit process flag (ujxudproc) 
determines whether the process run by a given user should be audited. The process is audited if the 
returned flag is I. If the returned flag is 0, the process is not audited. This caii is restricted to the super- 
user. 

RETURN VALUE ■ 

Upon successful completion, the audit process flag is returned; otherwise, a - 1 is returned and errno is | 

set to indicate the error. 

ERRORS 

getaudproc ( ) fails if the following is true: 

[EPERM] The caller is not the super-user. 

AUTHOR 

getaudproc ( ) was developed by HP. 

SEE ALSO 

setaudproc(2). 
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NAME 

getcontext - return process context for context-dependent file search 

SYNOPSIS 

#include <unistd.h> 

int getcontext (char *contextbuf, size_t length); 

DESCRIPTION 

getcontext ( ) reads the per-process context (see context(5)) into the buffer pointed to by contextbuf. The 
context is returned as a null-terminated string containing a blank-separated list of names. The function 
value returned by getcontext ( ) is the length of this string, including the null terminator. If this 
string, including the null terminator, is less than length bytes, a truncated, null-terminated string of length 
bytes is returned. In particular, if length is zero, only the function value is returned. 

RETURN VALUE 

Upon successful completion, the length of the context string, including the null terminator, is returned. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

getcontext ( ) may fail if the following is true: 

[EFAULT] contextbuf points to an illegal address. Reliable detection of this error is not guaranteed. 

EXAMPLES 

In the following example getcontext ( ) is called once with a length parameter of zero to determine the 
size of a buffer to allocate for the context. 

int length; 

char * contextbuf; 

length = getcontext ((char *)0, 0); 

contextbuf = malloc (length) ; 

(void) getcontext (contextbuf, length) ; 

AUTHOR 

getcontext ( ) was developed by HP. 

SEE ALSO 

getcontext(l), cnodeid(2), cnodes(2), cdf(4), context(5). 
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NAME 

getdirentries - get entries from a directory in a filesystem-independent format 

SYNOPSIS 

#include <ndir.h> 

int getdirentries ( 

int fildes, 

struct direct *buf, 

size_t nbytes, 

off_t *faasep 
); 

DESCRIPTION 

getdirentries ( ) places directory entries from the directory referenced by the file descriptor fildes into 
the buffer pointed to by buf, in a filesystem-independent format. Up to nbytes of data are transferred. 
nbytes must be greater than or equal to the block size associated with the file; see stat(2). Smaller block 
sizes can cause errors on certain file systems. 

The data in the buffer consists of a series of direct structures, each containing the following entries: 

unsigned long d_fileno; 

unsigned short d_reclen; 

unsigned short d_namlen; 

char d_name [MAXNAMLEN + 1 ] ; 

The d_f ileno entry is a number unique for each distinct file in the file system. Files linked by hard 
links (see link(2)) have the same d_f ileno. The d_reclen entry identifies the length, in bytes, of the 
directory record. The d_name entry contains a null-terminated file name. The d_namlen entry 
specifies the length of the file name. Thus the actual size of d_name can vary from 2 to MAXNAMLEN + 1. 
Note that the direct structures in the buffer are not necessarily tightly packed. The d_reclen entry 
must be used as an offset from the beginning of a di rect structure to the next structure, if any. 

The return value of the system call is the actual number of bytes transferred. The current position pointer 
associated with fildes is set to point to the next block of entries. The pointer is not necessarily incremented 
by the number of bytes returned by getdirentries ( ) . If the value returned is zero, the end of the 
directory has been reached. 

The current position pointer is set and retrieved by lseek() (see lseek(2). getdirentries () writes 
the position of the block read into the location pointed to by basep . The current position pointer can be set 
safely only to a value previously returned by lseek( ), to a value previously returned in the location 
pointed to by basep , or to zero. Any other manipulation of the position pointer causes undefined results. 

RETURN VALUE 

If successful, the number of bytes actually transferred is returned. Otherwise, - 1 is returned and errno 
is set to indicate the error. 

ERRORS 

getdirentries ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid file descriptor open for reading. 

[EPAULT] Either buf or basep points outside the allocated address space. 

[EINTR] A read from a slow device was interrupted by the delivery of a signal before any data 

arrived. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

AUTHOR 

getdirentries ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

open(2), lseek(2). 
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NAME 

getdomainname, setdomainname - get/set name of current Network Information Service domain 

SYNOPSIS 

int getdomainname (char *name # int namelen) ; 

int setdomainname (char *name # int namelen); 

DESCRIPTION 

getdomainname ( ) returns the name of the Network Information Service (NIS) domain for the current 
processor, as previously set by setdomainname ( ) . The parameter namelen specifies the size of the name 
array. The returned value is null-terminated unless the area pointed to by name is not large enough to 
hold the domain name plus the null byte. In this case, only the namelen number of bytes is returned. 

setdomainname ( ) sets the domain of the host machine to name, which has a length of namelen. This 
call is restricted to the super-user and is normally used only when the system is booted. 

These Network Information Service domains enable two distinct networks with common host names to 
merge. Each network is distinguished by having a different domain name. Currently, only the Network 
Information Service uses these domains. 

RETURN VALUE 

If the call succeeds, a value of is returned. If the call fails, a value of -1 is returned and er mo is set to 
indicate the error. 

ERRORS 

getdomainname ( ) and setdomainname ( ) fail if any of the following conditions are encountered: 

DEFAULT] name points outside the accessible address space. 

[EPERM] The caller is not super-user. This error only applies to setdomainname ( ) . 

WARNINGS 

The length of the name array should be at least 65; NIS domain names can be up to 64 characters long. 

NIS servers use the NIS domain name as the name of a subdirectory of /usr/etc/yp. Since the NIS 
domain name can be as long as 64 characters, the domain name set with setdomainname ( ) can exceed 
the maximum file name length allowed on the local file system. If that length is exceeded, the name of the 
subdirectory is the truncated NIS domain name. 

AUTHOR 

getdomainname was developed by Sun Microsystems, Inc. 

SEE ALSO 

domainname(l), ypserv(lM), ypfiles(4). 
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NAME 

getevent - get events and system calls that are currently being audited 

SYNOPSIS 

#include <sys/audit .h> 

int getevent ( 

struct aud_type *a_syscall / 

struct aud_event_tbl *a_event 
); 

DESCRIPTION 

getevent ( ) gets the events and system calls being audited. The events are returned in a table pointed 
to by ajevent. The system calls are returned in a table pointed to by ajsyscall. This call is restricted to the 
super-user. 

RETURN VALUE 

Upon successful completion, a value of is returned; otherwise, a -1 is returned and er mo is set to indi- 
cate the error. 

ERRORS 

getevent ( ) fails if the following is true: 

[EPERM] The caller is not super-user. 

AUTHOR 

getevent ( ) was developed by HP. 

SEE ALSO 

setevent(2), audevent(lM). 
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NAME 

getfli - return file handle for file on remote node 

SYNOPSIS 

#include <time.h> 
# include <rpc/rpc.h> 
#lnolude <errno s h> 
ttinclude <nfs/nfs.h> 

int getfh(char *path, fhandle_t *fhp); 

DESCRIPTION 

getf h ( ) returns a file handle in the struct pointed to by flip for the file pointed to by path. This informa- 
tion is used to perform an NFS mount for a remote node, getfh() is executed on the remote node; 
results are passed back to the program doing the NFS mount. The caller should never examine the file han- 
dle contents. The file handle only identifies a file to the node that produced the file handle. (The term "file 
handle" refers to an NFS concept.) 

Only the super-user can invoke getf h ( ) . 

RETURN VALUE 

Upon successful completion, getfh() returns 0; otherwise it returns -1 and sets errno to indicate the 
error. 

ERRORS 

getf h( ) fails if any of the following conditions are encountered: 

[EPERM] The effective user ID is not super-user. 

[ENOENT] File or directory specified bypath does not exist. 

[EINVAL] Invalid argument, or the file or directory has not been exported by export fs (see 

exportfs(1M)). 

[EREMOTE] The file or directory specified by path is a remote file or directory. 

WARNINGS 

This call should be used only by HP-supplied commands and is not recommended for use by non-HP- 
supplied programs. 

AUTHOR 

Sun Microsystems, Inc. 

SEE ALSO 

exportfs(lM), mount(lM), vfsmount(2). 
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NAME 

getgroups - get group access list 

SYNOPSIS 

#include <unistd.h> 

int getgroups ( int ngroups, gid_t gidset[]); 

DESCRIPTION 

getgroups ( ) gets the current group access list of the user process and stores it in the array gidset. The 
parameter ngroups indicates the number of entries which may be placed in gidset. No more than NGROUPS, 
as defined in <sys /param . h>, is ever returned. 

As a special case, if the ngroups argument is zero, getgroups ( ) returns the number of group entries for 
the process. In this case, the array pointed to by the gidset argument is not modified. 

EXAMPLES 

The following call to getgroups(2) retrieves the group access list of the calling process and stores the group 
ids in array mygidset: 

int ngroups = ngroups ; 
gid_t mygidset [ngroups] ; 
int ngrps; 

ngrps = getgroups (ngroups, mygidset); 

RETURN VALUE 

If successful, getgroups ( ) returns a non-negative value indicating the number of elements returned in 
gidset. If an error occurs, a value of -1 is returned and errno is set to indicate the type of error. 

ERRORS 

getgroups ( ) fails if any of the following conditions are encountered: 

[EFAULT] gidset specifies an invalid address. The reliable detection of this error is implementation 

dependent. 

[EINVAL] The argument ngroups is not zero and is less than the number of groups in the current 

group access list of the process. 

AUTHOR 

getgroups ( ) was developed by HP and the University of California, Berkeley 

SEE ALSO 

setgroups(2), initgroups(3C) 

STANDARDS CONFORMANCE 

getgroups ( ) : AES, XPG3, XPG4, FIPS 151-2, POSDC.l 
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NAME 

gethostname - get name of current host 

SYNOPSIS 

ttinclude <unistd.h> 

int gethostname (char *hostname, size_t size); 

DESCRIPTION 

gethostname ( ) returns in the array to which hostname points, the standard host name for the current 
processor as set by sethostname ( ) (see sethostname(2)). size specifies the length of the hostname array. 
hostname is null-terminated unless insufficient space is provided. 

RETURN VALUE 
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ERRORS 

gethostname ( ) can fail if the following is true: 

[EFAULT] hostname points to an illegal address. The reliable detection of this error is implementa- 

tion dependent. 

AUTHOR 

gethostname ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

hostname(l), uname(l), sethostname(2), uname(2). 
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NAME 

getitimer, setitimer - get/set value of interval timer 

SYNOPSIS 

ttinclude <time.h> 

int getitimer (int which, struct itimerval *value); 

int setitimer ( 

int which, 

const struct itimerval *value, 

struct itimerval *ovaiue 
); 

DESCRIPTION 

The system provides each process with three interval timers, defined in <time.h>. getitimer () 
returns the current value for the timer specified in which, whereas setitimer ( ) call sets the value of a 
timer (optionally returning the previous value of the timer). 

A timer value is defined by the itimerval structure: 

struct itimerval { 

struct timeval it_interval; /* timer interval */ 
struct timeval it_value; /* current value */ 

}; 

If it_value is non-zero, it indicates the time to the next timer expiration. If it_interval is non-zero, it 
specifies a value to be used in reloading itjvalue when the timer expires. Setting itjualue to disables a 
timer. Setting itjnterval to causes a timer to be disabled after its next expiration (assuming itjualue is 
non-zero). 

Time values smaller than the resolution of the system clock are rounded up to this resolution. The 
machine-dependent clock resolution is 1/HZ seconds, where the constant HZ is defined in 
<sys /param . h>. Time values larger than an implementation-specific maximum value are rounded down 
to this maximum. The maximum values for the three interval timers are specified by the constants 
MAX_ALARM, MAX_vTALARM, and MAX_PROP defined in <sys /param. h>. On all implementations, 
these values are guaranteed to be at least 31 days (in seconds). 

The which parameter specifies which timer to use. The possible values are ITIMER_REAL, 
ITIMER_VIRTUAL, and ITIMER_PROF. 

The ITIMER_REAL timer decrements in real time. A SIGALRM signal is delivered when this timer 
expires. 

The ITIMER_VIRTUAL timer decrements in process virtual time. It runs only when the process is exe- 
cuting. A SIGVTALRM signal is delivered when it expires. 

The ITIMER_PROF timer decrements both in process virtual time and when the system is running on 
behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of 
interpreted programs. Each time the ITIMER_PROP timer expires, the SIGPROP signal is delivered. 
Since this signal can interrupt in-progress system calls, programs using this timer must be prepared to res- 
tart interrupted system calls. 

Interval timers are not inherited by a child process across a fork ( ) , but are inherited across an exec ( ) . 

Three macros for manipulating time values are defined in <t ime . h>: 

timerclear Set a time value to zero. 

t ime r i s s et Test if a time value is non-zero. 

timercmp Compare two time values. (Beware that >= and <= do not work with the 

t ime r cmp macro .) 

The timer used with ITIMER_REAL is also used by alarm ( ) (see alarm{2)). Thus successive calls to 
alarm ( ) , getitimer ( ) , and setitimer ( ) set and return the state of a single timer. In addition, a 
call to alarm ( ) sets the timer interval to zero. 
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RETURN VALUE 

If the calls succeed, a value of is returned. If an error occurs, -1 is returned, and errno is set to indicate 
the error. 

ERRORS 

get it imer ( ) or set i timer ( ) fail if any of the following conditions are encountered: 

[EFAULT] The value structure specified a bad address. Reliable detection of this error is imple- 

mentation dependent. 

[EINVAL] A value structure specified a microsecond value less that zero or greater than or equal 

to one million. 

[EINVAL] which does not specify one of the three possible timers. 

EXAMPLES 

The following call to setitimer ( ) sets the real-time interval timer to expire initially after 10 seconds 
and every 0.5 seconds thereafter: 

struct itimerval rttimer; 
struct itimerval old_rttimer; 

rttimer. it_value.tv_sec =10; 

rttimer . it_value . tv_usec = ; 

rttimer. it_interval.tv_sec - 0; 

rttimer. it_interval.tv_usec « 500000; 

setitimer (ITIMER_REAL, fcrttimer, &old_rttimer) ; 

AUTHOR 

get it imer ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

alarm(2), exec(2), gettimeofday(2), signal(5). 
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NAME 

getpeername - get address of connected peer 

SYNOPSIS 

#include < sys/ socket .h> 

AF_CCITT only: 

ftinclude <x25/x25addrstr .h> 

int getpeername (int s, void *addr, int *addrlen) ; 

DESCRIPTION 

getpeername ( ) returns the address of the peer socket connected to the socket indicated by s, where s is 

a socket descriptor, addr points to a socket address structure in which this address is returned, addrlen 

points to an object of type int, which should be initialized to indicate the size of the address structure. On ■ 

return, it contains the actual size of the address returned (in bytes). If addr does not point to enough space | 

to contain the whole address of the peer, only the first addrlen bytes of the address are returned. 

AF_CCITT only: 

The addr struct contains the X.25 addressing information of the remote peer socket connected to socket s. 
However, the x2 5 if name [ ] field of the addr struct contains the name of the local X.25 interface through 
which the call arrived. 

RETURN VALUE 

Upon successful completion, getpeername ( ) returns 0; otherwise it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

getpeername ( ) fails if any of the following conditions are encountered: 

[EBADF] The argument s is not a valid file descriptor. 

[ENOTSOCK] The argument s is a file, not a socket. 

[ENOTCONN] The socket is not connected. 

[ENOBUFS] Insufficient resources were available in the system to perform the operation. 

[EFAULT] The addr or addrlen parameters are not valid pointers. 

[EINVAL] The socket has been shut down. 

[EOPNOTSUPP] Operation not supported for AFJJNIX sockets. 

AUTHOR 

getpeername ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

bind(2), socket(2), getsockname(2), inet(7F), af_ccitt(7F). 
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NAME 

getpid, getpgrp, getppid, getpgrp2 - get process, process group, and parent process ID 

SYNOPSIS 

ftinclude <unistd.h> 

pid_t getpid (void) ; 
pid_t getpgrp (void) ; 
pid_t getppid (void) ; 
pid_t getpgrp2 (pid_t pid) ; 
DESCRIPTION 
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ge tp id ( ) Process ID of the calling process. 

getpgrp ( ) Process group ID of the calling process. 

getppid ( ) Parent process ID of the calling process. 

getpgrp2 ( ) Process group ID of the specified process. If pid is zero, the call applies to the 
current process. For this to be allowed, the current process and the referenced 
process must be in the same session. 

ERRORS 

getpgrp2 fails if any of the following conditions are encountered: 

[EPERM] The current process and the specified process are not in the same session. 

[ESRCH] No process can be found corresponding to that specified by pid . 

AUTHOR 

getpid(), getppid(), getpgrpO, and getpgrp2 ( ) were developed by HP, AT&T, and the 
University of California, Berkeley. 

SEE ALSO 

exec(2), fork(2), setpgrp(2), setpgid(2), signal(5). 

STANDARDS CONFORMANCE 

getpid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

getpgrp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
getppid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

getpriority, setpriority - get and set process priorities 

SYNOPSIS 

#include <sys/ resource. h> 

int getpriority (int which, int who); 

int setpriority (int which, int who, int priority); 

DESCRIPTION 
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setpriority ( ) sets the priority of the indicated processes to priority . 

The processes are indicated by which and who, where which can have one of the following values: 

PRIO_PROCESS 

Get or set the priority of the specified process where who is the process ID. A who of 
implies the process ID of the calling process. 

PRI0_P6RP Get or set the priority of the specified process group where who is the process-group 
ID, indicating all processes belonging to that process-group. A who of implies the 
process-group ID of the calling process. 

PRIO_USER Get or set the priority of the specified user where who is the user ID, indicating all 
processes owned by that user. A who of implies the user ID of the calling process. 

If more than one process is indicated, the priority returned by getpriority ( ) is the smallest valued 
priority of all the indicated processes, and setpriority ( ) sets the priority of all indicated processes. 

priority is a value between -20 and 20, where smaller values indicate better priorities. The default priority 
for a processes is 0, and negative priorities require appropriate privileges. 

RETURN VALUE 

On success, getpriority ( ) returns an integer in the range from -20 to 20, and setpriority ( ) 
returns 0. Otherwise, both return -1 and set er rno to indicate the error. See WARNINGS below. 

ERRORS 

getpriority () and setpriorityO fail if any of the following conditions are encountered: 

[ESRCH] Processes indicated by which and who cannot be found. 

[EINVAL] which is not one of the choices listed above. 

[EACCES] The calling process does not have access rights to change one or more of the indicated 
processes. All processes for which access is allowed are still affected. 

[EPERM] The calling process attempted to change the priority of a process to a negative value 
without having appropriate privileges. 

WARNINGS 

Note that getpriority ( ) can return -1 when it successfully finds a priority of -1, and when it fails. To 
determine whether a failure occurred, set errno to before calling getpriority ( ) then examine 
errno after the call returns. 

AUTHOR 

setpriority ( ) and getpriority ( ) were developed by the University of California, Berkeley. 

SEE ALSO 

nice(l), renice(l), nice(2). 
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NAME 

getprivgrp, setprivgrp - get and set special attributes for group 

SYNOPSIS 

#include <sys/privgrp.h> 

int getprivgrp (struct privgrp_map *grplist); 
int setprivgrp (gid_t grpid, const int *mask) ; 

DESCRIPTION 

setprivgrp ( ) associates a kernel capability with a group ID. This allows subsetting of super-user-like 
privileges for members of a particular group or groups, setprivgrp () takes two arguments: the 
integer group id and a mask of permissions. The mask is created by treating the access types denned in 
<sys/privgrp .h> as bit numbers (using 1 for the least significant bit). Thus, privilege number 5 would 
be represented by the bit 1«(5-1) or 16. More generally, privilege p is represented by: 

mask[((p-l)/ BITS_PER_INT)] & (1 « ((p-1) % BITS_PER_INT)). 

As it is possible to have more than word size distinct privileges, mask is a pointer to an integer array of 
size PRIV_MASKSIZ. 

setprivgrp ( ) privileges include those specified in the file <sys/privgrp.h>. A process can access 
the system call protected by a specific privileged group if it belongs to or has an effective group ID of a group 
having access to the system call. All processes are considered to belong to the pseudo-group 
PRIV_GLOBAL. 

Specifying a grpid of PRIV_NONE causes privileges to be revoked on all privileged groups having any of 
the privileges specified in mask. Specifying a. grpid of PRIV_GLOBAL causes privileges to be granted to 
all processes. 

The constant PRIV_MAXGRPS in <sys/privgrp.h> defines the system limit on the number of groups 
that can be assigned privileges. One of these is always the psuedo-group PRIV_GLOBAL , allowing for 
PRIV_MAXGRPS - 1 actual groups. 

getprivgrp ( ) returns a table of the privileged group assignments into a user supplied structure, grplist 
points to an array of structures of type privgrp_map associating a groupid with a privilege mask. 
Privilege masks are formed by ORing together elements from the access types specified in 
<sys/privgrp .h>. The array may have gaps in it distinguished as having a priv_groupno field of 
PRIV_NONE. The group number PRIV_GLOBAL gives the global privilege mask. Only information about 
groups which are in the user's group access fist, or about his real or effective group id, is returned to an 
ordinary user. The complete set is returned to the privileged user. 

EXAMPLES 

The following example prints out PRI V_GLOBAL and the group IDs of the privilege groups to which the 
user belongs: 

# include <sys/types.h> 

struct privgrp_map pgrplist [PRIV_MAXGRPS] ; 
int i; 
gid_t pgid; 

getprivgrp (pgrplist); 

for (i=0; i<PRIV_MAXGRPS; i++) { 

if ((pgid = pgrplist [i] .priv_groupno) != PRIV_NONE) { 
if (pgid == PRIV_GLOBAL) 

printf ("(PRIV_GLOBAL) "); 
printf ("privilege group id = %d\n", pgid); 
} 
} 

NOTES 

Only users with the #idfef Bl setprocident privilege 
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NAME 

getrlimit, setrlimit - control consumption of system resources 

SYNOPSIS 

#include <sys/resource.h> 

int getrlimit (int resource, struct rlimit *rlp); 

int setrlimit (int resource, const struct rlimit *rlp); 

DESCRIPTION 

setrlimit ( ) sets a limit on consumption of system resources by the current process and each process it 
creates, getrlimit ( ) is used to obtain the value of the current limit. 

Each call to either getrlimit ( ) or setrlimit ( ) identifies a specific resource to be operated upon as _ 

well as a resource limit. A resource limit is a pair of values: one specifying the current (soft) limit, the I 

other a maximum (hard) limit. Soft limits can be changed by a process to any value that is less than or ■ 

equal to the hard limit. A process can irreversibly lower its hard limit to any value that is greater than or 
equal to the soft limit. Only users with appropriate privileges can raise a hard limit. Both hard and soft 
limits can be changed in a single call to setrlimit ( ) , subject to the constraints described above. 

The resource parameter selects the system resource limits to be set or retrieved. The possible values for 
resource are defined in <sys/resource .h>. Currently, only the following values are supported: 

RLIMIT_NOPILE the maximum number of files a process can have open. The soft limit for this 
resource is the same as the value returned by 
sysconf (_SC_OPEN_MAX) . 

RLIMIT_OPEN_MAX defined to be the same as RLIMIT_NOPILE. 

The rip argument points to an object of type struct rlimit, which is defined in <sys /resource. h>, and 
includes the following members: 

int rlim_cur Current (soft) limit 
int rlim_max Hard limit 

For getrlimit ( ) , the system stores the two limits on the specified resource in the structure to which rip 
points. 

For setrlimit (), the system reads new values for the two limits on the specified resource from the 
structure to which rip points. 

RETURN VALUE 

Upon successful completion, getrlimit () and setrlimit () return a value of 0. Otherwise, a value 
of -1 is returned, the limits on the resource and the rip structure are unchanged, and errno is set to indi- 
cate the error. 

ERRORS 

getrlimit ( ) and setrlimit ( ) fail if: 

[EFAULT] The address specified for rip is invalid. Reliable detection of this error is implementa- 

tion dependent. 

[EINVAL] The number specified for resource is invalid. 

setrlimit fails if: 

[EPERM] 

The rip argument specified a hard or soft limit higher than the current hard limit 
value, and the caller does not have appropriate privileges. 

[EINVAL] A user with appropriate privileges has attempted to raise rlp->rlim_cur or 

rip ->rlim_max to a value greater than the system is capable of supporting. 

[EINVAL] The value of rlp->rlim_cur is less than the number of file descriptors the process 

already has allocated. 

[EINVAL] The value of rip ->rlim_max is less than the current soft limit. 
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AUTHOR 

getrlimit ( ) and setrlimit ( ) were developed by HP, AT&T, and the University of California, 
Berkeley. 

SEE ALSO 

sysconf(2). 
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NAME 

getsockname - get socket address 

SYNOPSIS 

#include < sys/ socket .h> 

AF_CCITT only: 

ttinclude <x25/x25addrstr.h> 

int getsockname (int s, void *addr, int *addrlen) ; 

DESCRIPTION 

getsockname ( ) returns the address of the socket indicated by s, where s is a socket descriptor, addr 

points to a socket address structure in which this address is returned, addrlen points to an int which 

should be initialized to indicate the size of the address structure. On return it contains the actual size of ■ 

the address returned (in bytes). If addr does not point to enough space to contain the whole address of the | 

socket, only the first addrlen bytes of the address are returned. 

AF_CCITT only: 

The x25_host [ ] field of the addr struct returns the X.25 addressing information of the local socket s. 
The x2 5 if name [ ] field of the addr struct contains the name of the local X.25 interface through which the 
call arrived. 

RETURN VALUE 

Upon successful completion, getsockname () returns 0; otherwise, it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

getsockname ( ) fails if any of the following conditions are encountered: 

[EBADF] s is not a valid descriptor. 

[ENOTSOCK] s is a file, not a socket. 

[ENOBUFS] Insufficient resources were available in the system to perform the operation. 

[EFAULT] The addr or addrlen parameters are not valid pointers. 

[EINVAL] The socket has been shut down. 

[EOPNOTSUPP] Operation not supported for AFJJNIX sockets. 

AUTHOR 

getsockname ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

bind(2), socket(2), getpeername(2), inet(7F), af_ccitt(7F). 
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NAME 

getsockopt, setsockopt - get and set options on sockets 

SYNOPSIS 

#include < sys/ socket .h> 

int getsockopt ( 
int s, 
int level, 
int opt name, 
void * optval, 
int *optlen) ; 

int setsockopt ( 
int s, 
int level, 
int optname, 
const void *optval, 
int opt 1 en) ; 

DESCRIPTION 

getsockopt () and setsockopt () manipulate options associated with a socket. The socket is 
identified by the socket descriptor s. Options can exist at multiple protocol levels^ and they are always 
present at the uppermost "socket" level (see socket(2)). 

When manipulating socket options, the level at which the option resides (level) and the name of the option 
(optname) must be specified. To manipulate options at the "socket" level, level is specified as 
SOL_SOCKET. 

There are two kinds of options: boolean and non-boolean. Boolean options are either set or not set and also 
can use optval and optlen (see below) to pass information. Non-boolean options always use optval and 
optlen to pass information. 

To determine whether boolean option optname is set, the return value of getsockopt ( ) must be exam- 
ined. If the option is set, getsockopt ( ) returns without error. If the boolean option is not set, get- 
sockopt ( ) returns -1 and errno is set to indicate the error. 

For setsockopt ( ) , the parameters optval and optlen are used to pass option information from the sys- 
tem to the calling process, optval is the address of a location in memory that contains the option informa- 
tion to be passed to the system, optlen is an integer that specifies the size in bytes of the option informa- 
tion. 

For getsockopt ( ) , optval and optlen are used to pass option information from the system to the calling 
process, optval is the address of a location in memory that contains the option information to be passed to 
the calling process, or (char *) NULL if the option information is not of interest and not to be passed to the 
calling process, optlen is an address of an integer initially used to specify the maximum number of bytes of 
option information to be passed. If optval is not (char *) NULL, optlen is set on return to the actual number 
of bytes of option information passed. If the getsockopt () call fails, no option information is passed. 

optname and any specified options are passed uninterpreted to the appropriate protocol module for interpre- 
tation. The include file <sys /socket .h> contains definitions for "socket" level options (see socket(2)). 
Options at other protocol levels vary in format and name. Consult the appropriate entries in Section 7P, 
such as tcp(TP). 

The "socket" level options defined in the include file <sys /socket . h> are explained below: 

SO_DEBUG (boolean option) no functionality; included only for compatibility. 

SO_DONTROUTE (boolean option; SOCK.STREAM sockets only) causes outgoing messages to 

bypass standard routing facilities and to be routed by the network portion 
of the Internet address. 

SO_ERROR returns the current contents of the variable so_error for this socket and 

then clears the variable (so_error is defined in <sys/ socket var.h>. 
The contents match those found in errno. 
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SO_REUSEADDR (boolean option; AFJNET sockets only) allows local address reuse. 

SO_KEEPALIVE (boolean option; SOCK.STREAM and AFJNET «<«« getsockopt.2 sockets 

only) keeps otherwise idle connections active. If a connection has been idle 
for two hours, transmissions are forced every 75 seconds until a response is 
received or 10 minutes expires, whichever occurs first. If 10 minutes 
expires with no response, the connection is dropped. 

SO_LINGER (boolean option; SOCK.STREAM and AFJNET sockets only) lingers on close 

if data is present. For SO_LINGER, optval points to a struct linger 
/ defined in /usr/include/sys/soeket.h. The linger structure 
contains an integer boolean flag to toggle behavior on/off and an integer 
linger value. 

SO_BROADCAST (boolean option; SOCKJDGRAM and AFJNET sockets only) toggles permis- 

sion to transmit broadcast messages. 

SO_RCVBUP (non-boolean option) For stream sockets it changes the buffer size of a 

socket's receive socket buffer. For datagram sockets it changes the max- 
imum size message a socket can receive. A stream socket's buffer size can 
be increased at any time but decreased only prior to establishing a connec- 
tion. For datagram sockets, the inbound maximum message size can be 
increased or decreased at any time. The default and maximum values for 
SO_RCVBUP are protocol-specific. Refer to the appropriate entries in Sec- 
tions 7F and 7P. 

SO_SNDBUP (non-boolean option) For stream sockets, it changes the buffer size of a 

socket's send socket buffer. For datagram sockets it changes the maximum 
size message that can be sent. A stream socket's buffer size can be 
increased at any time but decreased only prior to establishing a connec- 
tion. For datagram sockets, the maximum outbound message size can be 
increased or decreased at any time. The default and maximum values for 
SO_SNDBUF are protocol-specific. Refer to the appropriate entries in Sec- 
tions 7F and 7P. 

SO_USELOOPBACK (boolean option) no functionality; included only for compatibility. 

None of the boolean options are supported for SOCKJ3GRAM sockets. 

If SO_DONTROUTE is set, the system does not use the network routing tables when determining which 
interface to use to send an outbound message. Instead, the system sends the message out through the 
interface that has a configured address matching the address to which the message is intended to be sent. 
If SO_DONTROUTE is not set, the system uses the network routing tables. 

SO_REUSEADDR indicates the rules used in validating addresses supplied in a bind ( ) call should allow 
reuse of local addresses. This allows multiple SOCKJ3TREAM sockets to be bound to the same local address, 
as long as all existing sockets at the desired address are in a connected state before the bind ( ) is done on 
the new socket. The SO_REUSEADDR option has no effect on SOCK.DGRAM sockets. 

The SO_KEEPALIVE option defaults to off. If SO_KEEPALIVE is set on and the connection has been idle 
for two hours, TCP sends a packet to the remote socket to acknowledge that it is still alive. If the remote 
socket does not respond within 75 seconds, TCP sends another packet. If TCP sends a total of 8 packets 
without response from the remote socket (i.e., 10 minutes have passed), TCP drops the connection. The 
next socket call (e.g., recv ( ) ) returns an error, and er rno is set to ETIMEDOUT. 

SO_LINGER controls the actions taken when unsent messages are queued on a SOCKJ3TREAM socket and a 
close(2) is performed. If SO_LINGER is toggled on with a non-zero linger interval, the system blocks the 
process on the close ( ) attempt until it is able to transmit the data or until it decides it is unable to 
deliver the information. If SO_LINGER is toggled on with a linger interval of zero, the connection is 
immediately terminated on the close ( ) of the socket, and any unsent data queued on the connection is 
lost. If SO_LINGER is toggled off (default upon socket creation) and a close () is issued, the call 
returns immediately. The system still gracefully brings down the connection by transmitting any queued 
data, if possible. SO_LINGER can be toggled on/off at any time during the life of an established connec- 
tion. Toggling SO_LINGER does not affect the action of shutdown ( ) . 



HP-UX Release 9.0: August 1992 



-2- 



79 



getsockopt ( 2 ) getsockopt ( 2 ) 



The SO_BROADCAST option requests permission to send Internet broadcast datagrams on the socket. 

For stream sockets, SO_RCVBUP and SO_SNDBUP can be used with getsockopt () to find the current 
sizes (in number of bytes) of the socket's receive and send buffers, respectively. If supported by the protocol, 
SO_RCVBUF and SO_SNDBUP can also be used with setsockopt ( ) to set the sizes (in number of 
bytes) of the socket's receive and send buffers, respectively. The sizes are passed as integer values using 
optval and optlen. You can increase a socket's buffer size at any time, but you can decrease it only prior to 
establishing a connection. The default and maximum buffer sizes are protocol-specific. See the appropriate 
entries in Sections 7F and 7P for more information. 

For datagram sockets, SO_RCVBUP and SO_SNDBUP can be used with getsockopt () to find the 
current maximum datagram size (in number of bytes) in the inbound and outbound direction, respectively. 
SO_RCVBUF and SO_SNDBUP can also be used with setsockopt ( ) to set the maximum datagram 
size. The default and maximum datagram sizes are protocol-specific. See the appropriate entries in Sec- 
tions 7F and 7P for more information. 

AF_CCITT 

SO_SNDBUP and SO_RCVBUF are the only options supported for sockets of the AF_CCITT address family. 

RETURN VALUE 

Upon successful completion, getsockopt () and setsockopt () return 0; otherwise, they return -1 
and set errno to indicate the error. 

DIAGNOSTICS 

getsockopt ( ) and setsockopt ( ) fail if any of the following conditions are encountered: 

[EBADF] The argument s is not a valid descriptor. 

[EOPNOTSUPP] The option is not supported by the protocol in use by the socket. 

[ENOBUFS] No buffer space is available. 

[ENOTSOCK] The argument s is a file, not a socket. 

[ENOPROTOOPT] In getsockopt ( ) , the requested option is currently not set. 

[EINVAL] The option is unknown at the socket level or the socket has been shut down. 

[EFAULT] The optval or, in the case of getsockopt ( ) , optlen parameters are not valid 

pointers. 

AUTHOR 

getsockopt ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P). 
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NAME 

gettimeofday, settimeofday - get/set date and time 

SYNOPSIS 

ttinclude <time.h> 

int gettimeofday( 

struct timeval *tp, 

struct timezone *tzp 
); 

int sett imeof day ( 

const struct timeval *tp, 

const struct timezone *tzp u 

I 

DESCRIPTION 

gettimeofday () returns and settimeofday ( ) sets the system's notion of the current Coordinated 
Universal Time (UTC) and the system's notion of the current time zone. Time is expressed in seconds and 
microseconds since midnight January 1, 1970. 

The structures pointed to by tp and tzp are denned in <time .h> as: 

struct timeval { 

unsigned long tv_sec; /* seconds since Jan. 1, 1970 */ 

long tv_usec; /* and microseconds */ 

}; 

struct timezone { 

int tz_minuteswest; /* of UTC */ 

int tz_dsttime; /* type of DST correction to apply */ 

h 

The t imezone structure indicates the local time zone (measured in minutes of time westward from UTC), 
and a flag that, if nonzero, indicates that Daylight Savings Time applies locally during the appropriate part 
of the year. Programs should use this timezone information only in the absence of the TZ environment vari- 
able. 

Only users with appropriate privileges can set the time of day. 

EXAMPLES 

The following example calls gettimeofday ( ) twice. It then computes the lapsed time between the calls 
in seconds and microseconds and stores the result in a timeval structure: 

struct timeval first, 

second, 

lapsed; 
struct timezone tzp; 

gettimeofday (fcfirst, &tzp) ; 
/* lapsed time */ 

gettimeofday (fcsecond, &tzp); 

if (f irst .tv_usec > second. tv_usec) { 

second. tv_usec += 1000000; 
s ec ond . t v_s ec - - ; 

} 

lapsed.tv_usec = second. tv_usec - f irst .tv_usec; 

lapsed. tv_sec = second . tv_sec - f irst .tv_sec; 

RETURN VALUE 

gett imeof day () and settimeofday () return on success; otherwise, if an error occurs, they 
return -1 and set errno to indicate the error. 
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ERRORS 

gettimeofday() and sett imeof day () failif any of the following conditions are encountered: 

[EFAULT] An argument address referenced invalid memory. The reliable detection of this error 

will be implementation dependent. 

[EPERM] A user lacking appropriate privileges attempted to set the time. 

WARNINGS 

The microsecond value usually has a granularity much greater than one due to the resolution of the system 
clock. Relying on any granularity (particularly of one) will render code non-portable. 

DEPENDENCIES 
Series 300/400 

gett imeof day ( ) has a granularity of 4 microseconds. 



Clustered Systems 

In an HP Clustered Environment, setting the time of day sets the date and timezone on all systems in the 
cluster. 

AUTHOR 

gett imeof day ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

date(l), stime(2), time(2), ctime(3C), privilege(5). 
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NAME 

getuid, geteuid, getgid, getegid - get real user, effective user, real group, and effective group IDs 

SYNOPSIS 

#include <unistd.h> 

uid_t getuid (void) ; 
uid_t geteuid (void) ; 
gid_t getgid (void) ; 
gid_t getegid(void) ; 

DESCRIPTION 

The following functions return the information indicated: 

getuid ( ) Real-user-ID of the calling process, 

geteuid ( ) Effective-user-ID of the calling process, 

getgid ( ) Real-group-ID of the calling process, 

getegid ( ) Effective-group-ID of the calling process. 

No means is available for ascertaining the saved-user-ID or saved-group-ID of a process. 

SEE ALSO 

setuid(2). 

STANDARDS CONFORMANCE 

getuid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

getegid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
geteuid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
getgid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 



I 
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NAME 

ioctl - control device 

SYNOPSIS 

#include <sys/ioctl.h> 

int ioctl (int fildes, int request, ... /* arg */); 

DESCRIPTION 

ioctl ( ) performs a variety of functions on character special files (devices). The write-ups of various dev- 
ices in Section (7) discuss how ioctl () applies to them. The type of arg is dependent on the specific 
ioctl ( ) call, as described in Section (7). 

request is made up of several fields which encode the size and direction of the argument (referenced by arg), 
as well as the desired command. An enumeration of the request fields are: 

IOC_IN Argument is read by the driver (meaning that the argument is copied from the 

application to the driver). 

IOC_OUT Argument is written by the driver (meaning that the argument is copied from 

the driver to the application). Ignored if an error occurs. 

IOCSIZE_MASK Number of bytes in the passed argument. A nonzero size indicates that arg is a 
pointer to the passed argument. A zero size indicates that arg is the passed 
argument (if the driver wants to use it), and is not treated as a pointer. 

IOCCMD_MASK The request command itself. 

When both IOC__IN and IOC_OUT are zero, it can be assumed that request is not encoded for size and 
direction, for compatibility purposes. Requests that do not require any data to be passed and requests that 
use arg as a value (as opposed to a pointer), have the IOC_IN bit set to one and the IOCSIZE_MASK 
field set to zero. 

The following macros are used to create the request argument, x andy are concatenated ( (x<<8 ) I y) to 
form IOCCMD and shifted into the proper location according to IOCCMD_MASK. t is the type (e.g. 
struct hpib_cmd) of the actual argument that the request references, and its size is taken and shifted 
into the appropriate place according to IOCSI ZE_MASK . 

_IOR(x,y,t) Sets IOC_OUT and initializes the values at IOCCMD_MASK and 

IOCSIZE_MASK accordingly. 

_IOW(x,y,t) Sets IOC_IN and initializes the values at IOCCMD_MASK and 

IOCSIZE_MASK accordingly. 

_IOWR(x,y, t) Sets both IOC_IN and IOC_OUT and initializes the values at 
IOCCMD_MASK and IOCSIZE_MASK. 

Note: any data structure referenced by arg must not contain any pointers. 

RETURN VALUE 

If an error has occurred, a value of -1 is returned and errno is set to indicate the error. 

ioctl ( ) fails if one or more of the following are true: IOC_OUT is ignored if an error occurs. 

[EBADF] fildes is not a valid open file descriptor. 

[ENOTTY] The request is not appropriate to the selected device. 

[EINVAL] request or arg is not valid. 

[EINTR] A signal was caught during the ioctl () system call. 

[EPERM] Typically this error indicates that an ioctl request was attempted that is forbidden in 

some way to the calling process. 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can 
affect the behavior described on this page. 

AUTHOR 

ioct 1 ( ) was developed by AT&T and HP. 
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SEE ALSO 

ioctl(5), termio(7). 

STANDARDS CONFORMANCE 

ioctl():SVID2,XPG2 



I 
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NAME 

ipcconnect - initiate a connection to another process 

SYNOPSIS 

ttinclude <sys/ns_ipc.h> 

void ipcconnect ( 

ns__int_t calldesc, 
ns_int_t destdesc, 
ns_int_t *flags, 
short opt [ ] , 
ns_int_t *vcdesc, 
ns_int_t *result); 

DESCRIPTION 

ipcconnect ( ) is used to initiate a virtual circuit on which data can be sent and received. When 
ipcconnect ( ) returns, a connection is not yet established; a successful return only indicates that a con- 
nection request was sent without error. Actively establishing a virtual circuit with NetlPC calls is a two- 
step process: 

• ipcconnect ( ) is called to request a connection, then 

• ipcrecv(3N) is called to find out if a connection initiated with ipcconnect ( ) was successfully 
established. 

The opt parameter can be used to specify the number of bytes you expect to send and receive on the connec- 
tion. The default for both sending and receiving is 100 bytes. This information is passed to the underlying 
protocol. When TCP is the underlying protocol, it limits the number of bytes that can be queued on a socket 
to the specified value. 

PARAMETERS 

calldesc (input parameter) 

NS_NULL_DESC should be specified. A valid call socket descriptor can be specified to 
ensure backward compatibility. 

destdesc (input parameter) 

A destination descriptor obtained by calling ipclookupO or ipcdest ( ) (see 
ipclookup(SN) and ipcdest(SN)). 

flags (input parameter) 

Either or a pointer to 0. All other values are reserved for future use. 

opt (input parameter) 

Options for this call. If no options are used, this parameter can be null. Otherwise, see 
below. 

vcdesc (output parameter) 

A pointer to a virtual circuit number that can be used in subsequent NetlPC calls to refer- 
ence the connection. 

result (output parameter) 

See ERRORS below. 

OPTION PARAMETER 

NSO_MAX_SEND_SIZE (optioncode = 3) (datalength = 2) A two-byte integer specifying the maximum 
number of bytes that can be sent with a single ipcsend ( ) call on this con- 
nection (see ipcsend(3N)). Range: 1 to 32 000 bytes. Default: 100 bytes. 

NSO_MAX_RECV_SIZE (optioncode = 4) (datalength = 2) A two-byte integer specifying the maximum 
number of bytes that can be received with a single ipcrecv ( ) call on this con- 
nection (see ipcrecv(SNJ). Range: 1 to 32,000 bytes. Default: 100 bytes. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 
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[NSR_ADDR_NOT_AVAIL] 

[NSR_BOUNDS_VIO] 

[NSR.DESC] 

[NSRJDESTUNREACHABLE] 

[NSR_DUP_OPTION] 
[NSR.FLAGS] 

[NSRJ£IND_AND_PROTOCOL] 
[NSR_MSGSIZE] 

[NSR_NO_DESC_AVAILABLE] 

[NSR_NO_ERROR] 

[NSR_NO_FILE_AVAILABLE] 

[NSR_NO_MEMORY] 

[NSR_NOT_ALLOWED] 

[NSR_NOT_CALL_SOCKET] 

[NSR_OPT_OPTION] 

[NSR_OPT_SYNTAX] 

[NSR.PROTOCOL] 

[NSR_SIGNAL_INDICATION] 



The protocol address specified by the destination descriptor is 0, which is 
illegal for connection establishment, OR there is no available interface to 
the destination network. 

A length or offset value in the option parameter is illegal or one of the 
pointer arguments is invalid. 

The calldesc argument is not NSR_NULL_DESC or a valid socket descrip- 
tor, or the destdesc argument is not a valid destination descriptor. 

The network or host specified by the destination descriptor is unreachable 
from this host at this time. 

A particular option is defined more than once in the opt parameter. 

An unsupported flag is set in the flags parameter. 

The requested protocol is not supported in the default domain. 

The value specified in NSO_MAX_SEND_SIZE or 

NSO_MAX_RECV_SIZE is invalid. 

The process exceeded the system-defined number of file and socket descrip- 
tors that can be open at a time (see getrlimit(2)). 

The call was successful. 

The system cannot allocate a file structure at this time. 

Sufficient system memory is not available to execute this call at this time. 

An unsupported flag is set in the flags parameter. 

The calldesc argument is not an NS_CALL socket. 

An option in the opt parameter is unknown or unsupported. 

A length or offset value in the opt parameter is invalid. 

The requested protocol is not supported. 

The call aborted due to a signal. 



AUTHOR 

ipcconnect ( ) was developed by HP. 

SEE ALSO 

getrlimit(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipccontrol - perform special operations on a NetlPC socket 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipccontrol ( 

ns_int_t descriptor, 
ns_int_t request, 
const void *wrtdata, 
ns_int_t wlen, 
void * readdata, 
ns_int_t *rlen, 
ns_int_t *flags, 
ns_int_t *result); 

DESCRIPTION 

ipccontrol ( ) is used to manipulate NetlPC sockets. The type of request is specified in the request 
parameter. Some parameters are optional and not used in all requests. If wrtdata is not used, wlen must 
be zero. If readdata is unused, Hen must be zero. 

All processes that own descriptors for a particular socket are affected by ipccontrol ( ) operations per- 
formed on that socket. For example, one process can change a socket's read or write threshold, synchronous 
timeout interval, or synchronous/asynchronous mode while another process is reading, writing, or selecting 
on that socket. Exactly when the process that is sharing the socket will be affected by these operations can- 
not be reliably predicted. Reads, writes, and selects in progress may complete after using either the previ- 
ous, new, or a combination of the previous and new values. 

Parameters 

descriptor (input parameter) 

The descriptor that refers to the socket to be manipulated. 

request (input parameter) 

Request code. Defines which operation is to be performed. See below. 

wrtdata (input parameter) 

A data buffer used to pass timeout and threshold information. 

wlen (input parameter) 

Length in bytes of the wrtdata data buffer. 

readdata (output parameter) 

A data buffer used to contain any data returned by the call. 

Hen (input/output parameter) 

The length in bytes of the readdata data buffer. On output, this parameter contains the 
total number of bytes returned to the process. 

flags (input parameter) 

Reserved for future use. This parameter should be or a pointer to 0. 



result 



(output parameter) 

The error code returned. See ERRORS below for more information. 



Request Parameter 

NSC_NBIO_ENABLE 

NSC_NBIO_DISABLE 
NSC TIMEOUT RESET 



(request code 1) 

Place socket referenced by descriptor in asynchronous mode. 

(request code 2) 

Place socket referenced by descriptor in synchronous mode. 

(request code 3) 

Change the referenced socket's synchronous timeout. The default timeout 
value is 60 seconds. The timeout value is specified in tenths of seconds (for 
example, a value of 1200 indicates 120 seconds). The new timeout value is 
treated as a 16-bit signed integer, and must be placed in the first two bytes 
of the wrtdata parameter. The timeout value must be in the range of zero 
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to 32 767. Negative values have no meaning and will result in an error. A 
value of zero sets the timeout to infinity. The timeout is not reset if the 
referenced socket is switched to asynchronous mode then back to synchro- 
nous mode. 

(request code 4) 

Return the synchronous timeout value for the socket referenced in the 
descriptor parameter. The timeout value is treated as a 16-bit signed 
integer, and is returned in the readdata parameter. 

(request code 1000^ 
Change the read threshold of the VC socket referenced in descriptor param- 
eter. Read thresholds are one byte by default. The descriptor parameter 
must reference a VC socket descriptor. The new read threshold value must be 
placed in the first two bytes of the wrtdata parameter. 

NSC_SEND_THRESH_RESET (request code 1001) 

Change the write threshold of the VC socket referenced in the descriptor 
parameter. Write thresholds are one byte by default. The descriptor 
parameter must reference a VC socket descriptor. The new write threshold 
value must be placed in the first two bytes of the wrtdata parameter. 



NSC TIMEOUT GET 



NSC RECV THRESH RESET 



NSC RECV THRESH GET 



NSC SEND THRESH GET 



NSC GET NODE NAME 



(request code 1002) 

Return the current write threshold for the VC socket referenced in the 
descriptor parameter. The descriptor parameter must reference a VC 
socket descriptor. The write threshold is treated as a 16-bit signed integer, 
and is returned in the readdata parameter. 

(request code 1003) 

Return the current read threshold for the VC socket referenced in the 
descriptor parameter. The descriptor parameter must reference a VC 
socket descriptor. The read threshold is treated as a 16-bit signed integer, 
and is returned in the readdata parameter. 

(request code 9008) 

Obsolescent. Use getnodename(2) instead. 



RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_BOUNDS_VIO] One of the pointer arguments is invalid. 

[NSR_DESC] The argument descriptor is not a valid NetlPC socket descriptor. 

[NSR_DLEN] The specified wlen or Hen parameter is invalid. 

[NSR_NO_ERROR] The call was successful. 

[NSRJREQUEST] The request was unknown. 

[NSRJTIMEOUTVALUE] An illegal timeout value was specified. 

[NSR_THRESH_VALUE] An illegal threshold value was specified. 

AUTHOR 

ipccontrol ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnamerase(2), 



ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), 
initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 



ipcshutdown(2), addopt(3N), 
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NAME 

ipccreate - create a call socket 

SYNOPSIS 

#include<sys/ns_ipc.h> 

void ipccreate ( 

ns_iiit_t socketkind, 
ns_int_t protocol, 
ns_int_t * flags, 
short opt [ ] , 
ns_int_t *calldesc, 
ns_int_t *result); 

DESCRIPTION 

ipccreate is used to create a call socket for use with subsequent NetlPC calls to establish a virtual cir- 
cuit connection between two processes. 

A process can have a system-defined maximum number of descriptors open at a time (see getrlimit{2)). 
ipccreate ( ) returns an error if a process attempts to exceed this limit. This limit includes file descrip- 
tors, as well as socket descriptors and destination descriptors. These descriptors may reference sockets 
and/or files inherited by or otherwise opened by the process. 

The NSO_PROTOCOL_ADDRESS option (code 128) can be used to create a call socket with a specific proto- 
col address. The peer process, which must have a priori knowledge of this protocol address, can call 
ipcdest ( ) with this address to obtain a destination descriptor that will enable ipcconnect ( ) to con- 
nect to this call socket. 

PARAMETERS 

socketkind (input parameter) Must be NS_CALL. Other values are reserved for future use. 

protocol (input parameter) Indicates the protocol module that the calling process wants to access. 

Must be NSP_TCP or zero. Other values are reserved for future use. 

flags (input parameter) Must be or a pointer to 0. Other values are reserved for future use. 

opt (input parameter) See below. 

calldesc (output parameter) Call socket descriptor. Refers to the newly-created call socket. 

result (output parameter) See diagnostics section below for more information. 

Opt Parameter 

See initopt and addopt for more information on NetlPC option buffers. 

NSO_MAX_CONN_REQ_BACK 

(optioncode = 6) {datalength = 2) 

A two-byte integer specifying the maximum number of unreceived connection requests that 
can be queued to a call socket. If this value is not specified, the default maximum is used. 
Default: One request. Range: 1 to 20. (Note that a queue limit of one may be too few if 
many processes attempt to initiate connections to the call socket simultaneously. If this 
occurs, some connection requests will be automatically rejected.) 

NSO_PROTOCOL_ADDRESS 

{optioncode = 128) {datalength = 2) 

A two-byte integer specifying a protocol-specific address to be used by the newly-created 
call socket. If this option is not specified, or if zero is specified, Net.SM IPC dynamically 
allocates an address. You must have super-user capability to request protocol addresses 
less than 1024. Recommended Range: 30 767 through 32 767. If the protocol is TCP then 
this option specifies the TCP port. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_BOUNDS_VIO] One of the pointer arguments is invalid. 
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[NSR_DUP_ADDRESS] The protocol address specified in the NSO_PROTOCOL_ADDRESS option is in 

use. 

[NSR_DUP_OPTION] A particular option is defined more than once in the opt parameter. 

[NSR_FLAGS] The flags parameter was not or a pointer to 0. 

[NSR_KIND_AND_PROTOCOL] 

The requested protocol is not supported in the default domain. 

[NSR_MAX_CONNECTQ] The NSO_MAX_CONN_REQ_BACK option must be greater than and less than 
20. 

[NSR_NO_DESC_AVAILABLE] 

The process exceeded the system-defined number of file and socket descriptors 
that can be open at a time (see getrlimit(2)). 



[NSR_NO_ERROR] 



The call was successful. 



[NSR_NO_FILE_AVAILABLE] 



[NSR_NO_MEMORY] 
[NSR_NOT_ALLOWED] 

[NSR_OPT_OPTION] 
[NSR_OPT_SYNTAX] 
[NSR.PROTOCOL] 



The system cannot allocate a file structure at this time. 

Sufficient system memory is not available to execute this call at this time. 

The protocol address specified via the NSO_PROTOCOL_ADDRESS option was 
less than 1024 and the program did not have super-user capability. 

An option specified in the opt parameter is unknown or unsupported. 

A length or offset value in the opt parameter is invalid. 

The combination of the protocol parameter and socketkind parameter could not 
be satisfied. At least one is incorrect. 



AUTHOR 

ipccreate ( ) was developed by HP. 

SEE ALSO 

getrlimit(2), ipcconnect(2), ipccontrol(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcsnutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcdest - create a NetlPC destination descriptor 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcdest ( 

ns_int_t socketkind, 
const char *nodename / 
ns_int_t node 1 en, 
ns_int_t protocol, 
short *protoaddr, 
ns_int_t protolen, 
ns__int_t * flags, 
short opt t ] , 
ns__int_t *destdesc, 
ns_int_t *result); 

DESCRIPTION 

ipcdest ( ) creates a destination descriptor which the calling process can use to establish a connection to 
another process. 

ipcdest ( ) can be used to obtain a destination descriptor for a call socket with a particular protocol 
address. To create a call socket with a particular address, use ipccreate ( ) with the 
NSO_PROTOCOL_ADDRESS option (see ipccreate(3N)). 

ipcdest ( ) does not verify that the remote endpoint described by the input parameters exists. This 
evaluation is delayed until the destination descriptor is used in a subsequent ipcconnect ( ) call. 

Parameters 

socketkind (input parameter) Defines the type of socket. Must be NS_CALL or 3 to specify a call 

socket. Other values are reserved for future use. 



nodename 



nodelen 

protocol 

protoaddr 
protolen 

flags 

opt 

destdesc 

result 



(input parameter) The ASCII-coded name that identifies the node where the call socket 
with protoaddr resides. Default: The organization, organization and domain, or all 
parts of the node name can be omitted. When organization or organization and 
domain are omitted, they default to the local organization and/or domain. If the 
nodelen parameter is set to zero, this parameter is ignored and the node name 
defaults to the local node. 

(input parameter) The length in bytes of the nodename parameter. Zero indicates 
that the nodename parameter is ignored, and the node name defaults to the local 
node. A fully-qualified node can be up to 50 bytes long. 

(input parameter) Defines the Transport Layer protocol to be used. Must be 
NSP_TCP or 4 to indicate the Transmission Control Protocol (TCP). Other values are 
reserved for future use. 

(input parameter) A data buffer that contains a TCP protocol address. 

(input parameter) The length in bytes of the protocol address. TCP protocol addresses 
are two bytes long. 

(input parameter) This parameter is reserved for future use. All bits must be clear 
(not set). 

(input parameter) No options are defined for this call. You must set this parameter to 
zero (0) or pass the constant (C programs only) NSO_NULL. 

(output parameter) Destination descriptor. Can be used in a subsequent ipccon- 
nect call to establish a connection to the call socket with protoaddr. 

(output parameter) See ERRORS below. 



RETURN VALUE 

None. Errors are returned in the result parameter. 
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ERRORS 

[NSR_NO_ERROR] 

[NSR_BOUNDS_VIO] 

[NSR_NOT_CALL_SOCKET] 

[NSR.FLAGS] 

[NSR_OPT_OPTION] 

[NSR.PROTOCOL] 

[NSR_KIND_AND_PROTOCOL] 

[NSR_ADDR_OPT] 

[NSRJSTLEN] 

[NSR_NODE_NAME_SYNTAX] 

[NSR_NO_NODE] 

[NSR_NO_MEMORY] 

[NSR_PATH_REPORT] 

[NSR_DEST_UNREACHABLE] 

[NSR_NO_FILE_AVAIL] 

[NSR_NO_DESC_AVAIL] 



The call was successful. 

A parameter address is invalid. 

The socketkind parameter is not NS_CALL. 

The value in the flags parameter is invalid. 

An option specified in the opt parameter is unknown or unsupported. 

The protocol of the specified socket is not supported by the local system. 

The socketkind and protocol parameters are not compatible. 

The value in the protolen parameter is invalid. 

The value in the nodelen parameter is invalid. 

The node specified in the nodename parameter is invalid. 

The specified node is unknown to the local host. 

Sufficient system memory is not available to execute this call at this time. 

The path report could not be interpreted. 

The path report contained no usable paths. 

No file table entries are available at this time. 

The process exceeded the system-defined number of file and socket descrip- 
tors that can be open at a time (see getrlimit{2)). 



AUTHOR 

ipcdest ( ) was developed by HP. 

SEE ALSO 

getrlimit(2), ipcconnect(2), ipccontrol(2), ipccreate(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcgetnodename - obtain NetlPC node name of current host 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcgetnodename ( 
char * nodename- 
ns_int_t *size, 
ns_int_t *result); 

DESCRIPTION 

ipcgetnodename ( ) returns the NetlPC node name for the current processor as set by setno- 
dename ( ) in the array to which nodename points (see setnodename{2)). 

Parameters 

nodename (input parameter) A pointer to a character array in which the ASCII-coded NetlPC node name 
is to be returned. 

size (input/output parameter) The length in bytes of the nodename array on input and the length of 

the returned NetlPC node name on output. 

result (output parameter) See ERRORS below. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_NO_ERROR] The call was successful. 

[NSR_NLEN] The value of the size parameter is not large enough for the NetlPC node name. 

[NSR_BOUNDS_VIO] Output parameter address is invalid. 

AUTHOR 

ipcgetnodename was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipclookup(2), ipcname(2), ipcnamerase(2), ipcrecv(2), 
ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipclookup - obtain a NetlPC destination descriptor 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipclookup ( 

const char * socket name, 
ns_int_t nlen, 
const char *nodename / 
ns int t nodslsn, 
ns_int_t *flags, 
ns_int_t *destdesc, 
ns_int_t *protocol, 
ns_int_t *socketkind, 
ns_int_t *result); 

DESCRIPTION 

ipclookup ( ) is used to obtain a destination descriptor for a named call socket. When supplied with 
valid socket and node names, ipclookup ( ) looks up the call socket in the socket registry at the node 
specified in the nodename parameter and returns a destination descriptor that can be used by subsequent 
NetlPC calls to locate the call socket. A destination descriptor is required by the ipcconnect ( ) call to 
provide the information necessary to direct a connection request to the proper node and call socket and thus 
initiate a connection. 

When a process attempts to look up a socket name in the appropriate socket registry, the name must be 
there or an NSR_NAME_NOT_FOUND error is returned to the calling process. When two processes are run- 
ning concurrently, it may be difficult to ensure that a socket name is placed in the socket registry prior to 
being "looked up" by another process. This problem is referred to as a race condition because the two 
processes are "racing" to see which one accesses the socket registry first. 

In order to avoid a race situation, the process that calls ipclookup () can test for a 
NSR_NAME_NOT_FOUND error in the call's result parameter. If this error is returned, the process can try 
again by entering a loop and repeating the ipclookup ( ) call for a specified number of times. The pro- 
cess should also call sleep () to suspend execution for an interval (see sleep (3 C), then repeat the 
ipclookup () call. 

Parameters 

socketname (input parameter) The name of the call socket to be "looked up". Uppercase and 

lowercase characters are treated as equivalent. 

nlen (input parameter) The length of the socketname parameter in characters. Maximum 

length is 16 characters. 

nodename (input parameter) The ASCII-coded name that that identifies the node where the 

socket specified in the socketname parameter resides. Default: organization, organi- 
zation and domain, or all parts of the node name can be omitted. When organization 
or organization and domain are omitted, they default to the local organization and/or 
domain. If the entire parameter is omitted, the node name defaults to the local node. 

nodelen (input parameter) The length in bytes of the nodename parameter. If zero is specified, 

NetlPC searches the local node's socket registry (see nodename parameter above for 
more information). 

flags (input parameter) This parameter is reserved for future use. All bits must be clear 

(not set). 

destdesc (output parameter) Destination descriptor. Refers to the descriptor that indicates the 

location of the named call socket. Can be used in subsequent NetlPC calls. 

protocol (output parameter) This parameter is reserved for future use. Zero (0) is always 

returned in this parameter. 

socketkind (output parameter) Identifies the socket's type. Can be used in an ipccreate ( ) 

call to create a socket of the appropriate type. 
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result (output parameter) See ERRORS below 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_NO_ERROR] 

[NSR_BOUNDS_VIO] 

[NSR_FLAGS] 

[NSR_PROTOCOL] 



The call was successful. 

A parameter address is invalid. 

The value in the flags parameter in invalid. 

The protocol of the socket specified by socketname is not supported by the 
local system. 

The value in the nodelen parameter is not valid. 

The string pointed to by nodename is invalid. 

nodename is unknown to the local host. 

Sufficient system memory is not available to execute this call at this time. 

The path report could not be interpreted. 

The specified socketname was not found in the socket registry. 

[NSR_CANT_CONTACT_SERVER] The ipc lookup ( ) request could not be sent to the remote socket regis- 
try server. 

No response was received from the remote socket registry server. 



LJNSKJNL^rM] 

[NSR_NODE_NAME_SYNTAX] 

[NSR_NO_NODE] 

[NSR_NO_MEMORY] 

[NSR_PATH_REPORT] 

[NSR_NAME_NOT_FOUND] 



[NSR_NO_REG_RESPONSE] 
[NSRVERSION] 

[NSR_BAD_REG_MSG] 

[NSR_NO_FILE_AVAIL] 
[NSR_NO_DESC_AVAIL] 



The reply from the remote socket registry indicates a version error 
occurred. 

A corrupt reply message was received from the remote socket registry 
server. 

No file table entries are available. 

The process exceeded the system-defined number of file and socket descrip- 
tors that can be open at a time (see getrlimil(2)). 



AUTHOR 

ipclookup ( ) was developed by HP. 

SEE ALSO 

getrlimit(2), ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N), sleep(3C). 
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NAME 

ipcname - associate a name with a call socket or destination descriptor 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcname ( 

ns_int_t descriptor, 
const char * socketname, 
ns_int_t nlen, 
ns_int_t *result); 

DESCRIPTION 

ipcname ( ) associates a name with a call socket and adds this information to the local node's socket regis- 
try. The name a process associates with a call socket must be known to its peer process so that the peer 
process can look up the name with an ipc lookup ( ) call. This can be accomplished by hard-coding the 
name into both processes or by passing the name from one process to another. 

The name associated with a call socket can be user-defined or randomly generated by NetlPC, and must be 
unique to your node (i.e., it cannot be simultaneously associated with two descriptors). For example, if a 
call to ipcname ( ) assigns the name Liz to a call socket, a subsequent call with Liz results in an 
error. To ensure that the name being assigned to a call socket is unique, use the random name generating 
feature of ipcname ( ) (see the nlen parameter below for more information). A call socket can be fisted 
under multiple names. 

ipcname ( ) always enters its listings into the local node's socket registry, ipc lookup ( ) , by contrast, 
can look up socket names at both the local node and at a remote node. Since "long distance" look-ups take 
longer than local look-ups, it may be helpful to use ipcname ( ) to name a destination descriptor associ- 
ated with a remotely named call socket. When a process names a destination descriptor, the name of the 
destination descriptor is placed in the local socket registry (the socket registry at the node where the calling 
process resides). This allows other processes to look up the name in the local socket registry rather than 
calling ipclookup( ) to look up the name in a socket registry at a remote node where the call socket 
resides. 

Using ipcname ( ) to name a destination descriptor is less reliable than looking up the socket name at the 
remote node because destination descriptors can become outdated. As a precaution, locally stored destina- 
tion descriptors should be refreshed periodically. 

ipcname ( ) cannot be used to name VC sockets. 

PARAMETERS 

descriptor (input parameter) The descriptor that references the call socket to be named. Can be 

a call socket descriptor or a destination descriptor. 

socketname (input/output parameter) The ASCII-coded name to be associated with the descriptor. 

Uppercase and lowercase characters are treated as equivalent. NetlPC can also 
return a randomly-generated name in this parameter (see the nlen parameter). 

nlen (input parameter) The length in characters of the socketname parameter. Maximum 

length is 16 characters. If zero is specified, NetlPC returns a random, eight-byte name 
in the socketname parameter. The eight-byte length is not returned in the nlen 
parameter. 

result (output parameter) See ERRORS below. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_NO_ERROR] The call was successful. 

[NSR_CANT_NAME_VC] The descriptor parameter corresponds to a VC socket and naming of VC sockets is 
not allowed. 

[NSR_DESC] The descriptor parameter does not correspond to a NetlPC socket. 
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[NSR.NLEN] 
[NSR_DUP_NAME] 
[NSR_NO_MEMORY] 
[NSR_BOUNDS_VIO] 



The value specified in the nlen parameter is invalid. 
The specified socketname already exists in the local socket registry. 
Sufficient system memory is not available to execute this call at this time. 
The output parameter address is invalid. 



AUTHOR 

ipcname ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcnamerase(2), 
ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N). optoverhead(3N), readopt(3N). 
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NAME 

ipcnamerase - delete a name associated with a NetlPC call socket or destination descriptor 

SYNOPSIS 

ftinclude <sys/ns_ipc.h> 

void ipcnamerase ( 

const char * socketname, 
ns_int_t nlen, 
ns_int_t *result); 

DESCRIPTION 

ipcnamerase ( ) can be called to remove listings from the local node's socket registry. Only the owner of 
a call socket or destination descriptor can remove the socket's name from the local socket registry. 

If a call socket descriptor or destination descriptor is destroyed by ipcshutdown ( ) or if its last owner 
terminates, any listings for it that exist at the local socket registry are automatically purged. 

If multiple processes have descriptors for the same socket, the first ipcnamerase ( ) call succeeds; subse- 
quent calls fail. 

Parameters 

socketname (input parameter) The ASCII-coded name that was previously associated with a call 

socket descriptor or destination descriptor via ipcname ( ) . Uppercase and lower- 
case characters are treated as equivalent. 

nlen (input parameter) The length in bytes of the specified name. Maximum length is 16 

bytes. 

result (output parameter) See ERRORS below. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_NO_ERROR] The call was successful. 

[NSR_NLEN] The value specified in the nlen parameter is invalid. 

[NSR_NAME_NOT_FOUND] The name specified by socketname does not exist in local socket registry. 

[NSR_NO_OWNERSHIP] The caller is not the owner of the named socket. 

AUTHOR 

ipcnamerase ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcrecv(2), 
ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcrecv - establish an NetlPC virtual circuit connection or receive data on an established connection 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcrecv ( 

ns_int_t vcdesc- 
void *data, 
ns_int_t *dlen, 
ns_int_t *flags, 
short opt [ ] , 
ns_int_t *result); 

DESCRIPTION 

ipcrecv ( ) serves two purposes: 

• Establish a virtual circuit connection that was initiated with ipcconnect ( ) (see ipcconnect(2)\ 

• Receive data on a previously established virtual circuit connection. 

After a program calls ipcconnect () , it must call ipcrecv () to complete the connection. When 
ipcrecv ( ) is called to finish establishing a connection, no data is returned in the data parameter and the 
dlen parameter is ignored. An exception ipcselect ( ) (see ipcselect(2)) can be performed to determine 
whether connections are pending on a call socket. 

When ipcrecv ( ) is called to receive data queued on a established connection, several different alterna- 
tives are available: 

• Normal reading: Data is moved from the connection queue into the user's buffer. 

• Preview reading: This alternative is specified by setting the NSF_PREVIEW bit (bit 30) of the flags 
parameter. When this bit is set, data is copied into the process's buffer, but still remains in the 
connection queue. Consequently, the next ipcrecv ( ) call reads the same data. 

• Vectored or "scattered" reading: The calling process can pass a data vector argument that 
describes one or more locations. Received data is then placed into these locations. This alternative 
can be used with both the normal and the preview read described above, and is specified by setting 
the NSF_VECTORED bit (bit 31) of the flags parameter. 

For vectored reads an iovec structure contains the data vector. An iovec structure can be denned as: 

struct iovec { 

char *iov_base; 

unsigned iov_len; 
}; 

and the normal type for the data argument can be replaced by: 

struct iovec *data; 

Each iovec entry specifies the base address and length of an area in memory where data should be placed, 
ipcrecv ( ) always fills one area completely before proceeding to the next area. 

ipcrecv ( ) behavior varies, depending on whether the socket referenced is in synchronous or asynchro- 
nous mode. A socket is in synchronous mode by default. It can be placed in asynchronous mode by calling 
ipccontrol ( ) (see ipccontrol(2)). By default, calls that block reach their timeout limit in 60 seconds. 
The length of the timeout period can be changed by calling ipccontrol ( ) . Refer to ipccontrol(2) for 
more information. 

If the socket referenced by ipcrecv ( ) is in synchronous mode and no data is queued on the connection, 
the call blocks until data arrives or the socket timer expires. 

If the socket referenced by ipcrecv ( ) is in asynchronous mode and no data is queued on the connection, 
NSR_WOULD_BLOCK is returned in the result parameter. 

Parameters 

vcdesc (input parameter) "virtual circuit" socket descriptor. Refers to a socket that: 
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data 



dlen 



flags 

opt 

result 



• Is the endpoint of a virtual circuit connection that has not yet been esta- 
blished, or 

• Is the endpoint of an established virtual circuit on which data will be 
received. 

(output parameter) A pointer to a data buffer for holding the received data, or a 
pointer to an array of data vectors describing the locations where the data is to be 
placed. 

(input/output parameter) If data is a data buffer, dlen is the maximum number of 
bytes that can be received. If data is a data vector, dlen refers to the length of the 
data vector in bytes. As a return parameter, dlen indicates how many bytes were 
actually received. If ipcrecv() is used to establish a connection (not to receive 
data), dlen is meaningless on input and a value of zero (0) is returned on output. 

(input/output parameter) See below. 

(input parameter) A pointer to a NetlPC options buffer. See below. 

(output parameter) The error code returned. Refer to ERRORS below for more infor- 
mation. 

Flags Parameter 

Flags are only valid on an established connection. 

NSF_DATA_WAIT (bit 20) 

(input parameter) This flag exists for backward compatibility. Existing 
programs that use this flag may suffer performance degradation due to 
network congestion avoidance algorithms in the networking protocol code. 
This flag should be removed from those programs. 

) 
(output parameter) This bit is always set for backwards compatibility. 

(input parameter) When this bit is set, data queued on the connection may 
be previewed. Data is placed in the data parameter but not removed from 
the connection queue. Since the data remains in the queue, the next 
ipcrecv ( ) call reads the same data. 

NSF_VECTORED (bit 31) (input parameter) When set, this bit indicates that data is a data vector 
and not a data buffer. 

Opt Parameter 

Options are only valid when ipcrecv ( ) is issued against an established connection. 



NSP_MORE_DATA (bit 26) 



NSP_PREVIEW (bit 30) 



NSO DATA OFFSET 



(optioncode = 8) (datalength = 2) A two-byte integer that defines a byte 
offset from the beginning of a data buffer where NetlPC is to begin placing 
data. This option is valid only if data is a data buffer and not a data vec- 
tor. 



RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 



[NSR_BOUNDS_VIO] 

[NSR.DESC] 
[NSRJDLEN] 
[NSR_DUP_OPTION] 
[NSR_MESSAGE_SIZE] 



A length or offset value in the opt parameter is illegal, or one of the pointer 
arguments is invalid. 

The vcdesc argument is not a valid socket descriptor 

The specified dlen parameter is invalid. 

A particular option is defined more than once in the opt parameter. 

The value in the dlen exceeds the maximum limit for this socket. The 
default maximum is 100 bytes. You can use ipccontrol ( ) to alter this 
value. 
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[NSR_NO_ERROR] 
[NSR_NOT_CONNECTION] 
[NSR_OPT_OPTION] 
[NSR_OPT_SYNTAX] 
rxTQU ou'iMrvpij' At»r»-DTn 



The call was successful. 

The vcdesc parameter did not reference a VC socket. 

An option specified in the opt parameter is unknown or unsupported. 

A length or offset value in the opt parameter is invalid. 
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[NSR_REMOTE_RELEASED] 
[NSR_SIGNAL_INDICATION] 
[NSR_SOCKET_TIMEOUT] 



InrroruM and 



The connection was released due to action by the peer. 
The call aborted due to a signal received. 
The socket timer expired: 

• Before the connection completed ^ first call to . 

the socket is in synchronous mode), 

• Before any data arrived (connection established, socket in syn- 
chronous mode, NSP_DATA_WAIT flag not set), or 

• Before the requested amount of data arrived (connection esta- 
blished, socket in synchronous mode, NSR_DATA_WAIT flag set). 

The number of data vectors exceeds the maximum limit of 16. 

A negative data length was specified in the iovec. 

The connection is still pending; the data present is less than requested, the 
socket in asynchronous mode, and the NSF_DATA_WAIT flag is set; or no 
data is present, and the socket is in asynchronous mode with the 
NSP_DATA_WAIT flag not set. 

AUTHOR 

ipcrecv ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 



[NSR_TOO_MANY_VECTS] 

[NSR.VECTCOUNT] 

[NSR_WOULD_BLOCK] 



102 



-3- 



HP-UX Release 9.0: August 1992 



ipcrecvcn(2) 



ipcrecvcn(2) 



NAME 

ipcrecvcn - receive a connection on a call socket 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcrecvcn ( 

ns_int_t calldesc, 
ns_int_t *vcdesc, 
ns_int_t * flags, 
short opt [ ] ; 
ns_int_t *result); 

DESCRIPTION 

Before calling ipcrecvcnO, ipccreate() must be called to create a new call socket. When 
ipcrecvcn ( ) is invoked against a call socket that has queued connection requests, it returns a virtual 
circuit (VC) socket descriptor to the calling process. The VC socket descriptor can be used with subsequent 
NetlPC calls to send and receive data. 

When a socket is created, it is placed in synchronous mode by default. A socket can be placed in asynchro- 
nous mode by calling ipccontrol ( ). When the call socket is in synchronous mode, ipcrecvcnO 
blocks until a connection request arrives or the synchronous socket timer expires. The timeout value can be 
altered by calling ipccontrol () . When the call socket is in asynchronous mode, ipcrecvcnO 
returns NSR_WOULD_BLOCK if no connection requests are queued for the call socket. 

An exception ipcselect ( ) can be performed on the referenced call socket to determine if connections 
are pending on a call socket. 

Parameters 

calldesc (input parameter) Socket descriptor. Refers to a call socket owned by the calling pro- 

cess. 



vcdesc 

flags 

opt 

result 



(output parameter) VC socket descriptor. Refers to a VC socket that is the end-point of 
an established virtual circuit connection. 

(input parameter) Must be 0. Other values are reserved for future use. 

(input parameter) See below. 

(output parameter) The error code returned. Refer to ERRORS below for more infor- 
mation. 

Opt Parameter 

NSO_MAX_SEND_SIZE (optioncode = 3) (datalength = 2) A signed two-byte integer that specifies the 
maximum number of bytes you expect to send with a single ipcsend( ) (see 
ipcsend(2)) call on the VC socket. Range: 1 to 32 000 bytes. Default: 100 bytes. 

NSO_MAX_RECV_SIZE (optioncode = 4) (datalength = 2) A signed two-byte integer that specifies the 
maximum number of bytes you expect to receive with a single ipcrecv ( ) (see 
ipcrecv(2)) call on this connection. Range: 1 to 32000 bytes. Default: 100 
bytes. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_DESC] calldesc is not a valid socket descriptor. 

[NSR_BOUNDS_VIO] A length or offset value in the opt parameter is invalid. 

[NSR_DUP_OPTION] A particular option is defined more than once in the opt parameter. 

[NSR_MSGSIZE] The value specified in NSO_MAX_SEND_SIZE or 

NSO MAX RECV SIZE is invalid. 



[NSR_NO_ERROR] 
[NSR_NOT_CALL_SOCKET] 



The call was successful. 
calldesc is not a call socket. 
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[NSR_OPT_OPTION] 
[NSR_OPT_SYNTAX] 
[NSR_SIGNAL_INDICATION] 
[NSR_SOCKET_TIMEOUT] 

rwau \I7Y~»TTT Tl dt ru~*wi 



The option in opt parameter is unknown or unsupported. 
A length or offset value in the opt parameter is invalid. 
A signal was received before a connection request arrived. 
The socket timer expired before a connection request arrived. 
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AUTHOR 

ipcrecvcn ( ) was developed by HP. 

SEE ALSO 

ipcconneet(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcselect - determine status of NetlPC socket 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcselect ( 

ns_int_t *sdbound, 
int readmap [ ] , 
int wr itemap [ ] , 
int except ionmap [ 1 , 
ns_int_t timeout, 
ns_int_t *result); 

DESCRIPTION 

ipcselect ( ) enables a process to detect and/or wait for the occurrence of any of several events across 
any of several sockets. A process should call ipcselect ( ) with map elements set for descriptors that it 
owns. If a process attempts to perform a select on a closed or invalid descriptor, an error is returned. Per- 
forming a select on a destination descriptor has no meaning and should be avoided. 

ipcselect ( ) reports three types of information: 

• Whether any of the referenced sockets are readable. A VC socket is considered readable if it can 
immediately satisfy an ipcrecv ( ) (see ipcrecv(2)) request for a number of bytes greater than or 
equal to its read threshold. The read threshold is one byte by default and can be modified by cal- 
ling ipccontrol ( ) (see ipccontrol(2)). Read selecting on a call socket has no meaning and 
should be avoided. 

• Whether any of the referenced sockets are writeable. A VC socket is considered writeable if it can 
immediately accommodate an ipcsend ( ) (see ipcsend(2)) request that involves a number of 
bytes greater than or equal to the socket's write threshold. The write threshold is one byte by 
default and can be modified by calling ipccontrol ( ) . Write selecting on a call socket has no 
meaning and should be avoided. 

• Whether any of the referenced sockets are exceptional. A VC socket is exceptional if it is not con- 
nected. A call socket is exceptional if it has a connection queued on it (i.e., if a subsequent call to 
ipcr ecvcn ( ) can succeed). 

When a socket is shared (i.e., more than one process has a descriptor for the same socket), an ipcsend ( ) 
call may return an NSR_WOULD_BLOCK error even if a previous ipcselect ( ) call indicated that the 
socket was writeable. For example, this would occur if another process (with a descriptor for the same 
socket) called ipcsend () after the original process called ipcselect () and before it called 
ipcsend(). 

The following are examples of read selecting, write selecting, and exception selecting using ipcselect ( ) . 

Detecting Connection Requests 

By setting bits in the exceptionmap parameter, a process can determine whether incoming connection 
requests are queued to certain call sockets. For example: Process A must determine whether certain 
call sockets have received connection requests. To do this, Process A calls ipcselect ( ) with the 
exceptionmap map elements set to correspond to these sockets. Assuming that the timeout interval is 
long enough (set by timeout parameter), ipcselect ( ) completes after at least one connection has 
been established and has been queued on one of the sockets specified in exceptionmap. When the call 
completes, only those elements remain set that correspond to sockets which have queued connections; 
the other elements will have been cleared. 

Performing a Read Select 

By setting elements in the readmap parameter, a process can determine whether certain VC sockets 
are readable. For example: Process A must determine which of its VC sockets have data queued to 
them. To do this, Process A performs a read select on those sockets by setting elements in the read- 
map parameter to correspond with the desired VC sockets. Upon completion of the call, only the ele- 
ments that represent readable sockets remain set; the other elements will have been cleared. Process 
A can call ipcselect ( ) with a zero-length timeout to determine the status of a socket immedi- 
ately, or with a non-zero timeout if it is willing to wait for data to arrive. 
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Performing a Write Select 

By setting bits in the writemap parameter, a process can determine whether certain VC sockets are 
writeable. For example: Process A must determine which of its VC sockets can accommodate a new 
ipcsend ( ) request, and which of its call sockets can accommodate a new ipcconnect ( ) request 
(see ipcsend(2) and ipcconnect(2)). To do this, it can perform a write select on these sockets by setting 
elements in the writemap parameter to correspond with the desired VC and call sockets. Upon comple- 
tion of the call, only the elements that represent writeable sockets will remain set; the other elements 
will have been cleared. Process A can call ipcselect ( ) with a zero-length timeout to determine 
the status of a socket immediately, or with a non-zero timeout if it is willing to wait before sending 
data on the connection. 

Exception Selecting 

By setting bits in the exceptionmap parameter, a process can determine whether certain connections 
have been aborted. VC sockets that reference aborted connections always exception select as "true" 
(their elements are set when the call completes). Exception selecting on VC sockets can also be useful 
when the connection associated with the socket is not fully established. For example: Process B has 
successfully created a VC socket via a call to ipcconnect ( ) , but cannot know whether the connec- 
tion associated with the socket is established until it calls ipcrecv(). If Process B calls 
ipcrecv ( ) before the connection is established or before it becomes known that the connection can- 
not be established, it will block if the VC socket is in synchronous mode, or return a 
NSR_WOULD_BLOCK error if the VC socket is in asynchronous mode. Process B can avoid blocking in 
the synchronous case, or polling in the asynchronous case, by performing an exception select on the 
new VC socket. The socket selects as true if the connection has become "established" but 
ipcrecv ( ) has not yet been called or if the attempt to connect has failed. 

Parameters 

sdbound (input/output parameter) Specifies the upper ordinal bound on the range of descrip- 

tors specified in the readmap, writemap, and exceptionmap parameters. An 
ipcselect () call is most efficient if sdbound is set to the ordinal value of the 
highest-numbered socket descriptor specified in the map parameters. As an output 
parameter, sdbound contains the upper ordinal boundary of all of the descriptors that 
met the select criteria. The maximum number of file and socket descriptors that a 
process can open at a time is a system-defined number (see getrlimit(2)). 

readmap (input/output parameter) A bit map indexed with NetlPC socket descriptors. On 

input, this parameter specifies the socket descriptors to be examined for readability. 
If zero is passed, no sockets are examined. On output, readmap describes all readable 
sockets. Readability is described above. 

writemap (input/output parameter) A bit map indexed with NetlPC socket descriptors. On 

input, this parameter specifies the socket descriptors to be examined for writeability. 
If zero is passed, no sockets will be examined. On output, writemap describes all 
writeable sockets. Writeablity is described above. 

exceptionmap (input/output parameter) A bit map indexed with NetlPC sockets descriptors. On 

input, this parameter specifies the socket descriptors to be examined for exceptions. If 
zero is passed, no sockets will be examined. On output, exceptionmap describes all 
exceptional sockets. Exception conditions are described above. 

timeout (input parameter) The number of tenths of seconds to wait. If no sockets are select- 

able, ipcselect ( ) blocks for this amount of time. Valid values are zero, -1, or any 
positive integer. If timeout is set to zero, the call will not block. If timeout is set to -1, 
the call blocks until some event occurs. NOTE: If timeout is set to -1 and no bits are 
set in any of the bit maps, ipcselect ( ) blocks indefinitely. 

result (output parameter) The error code returned. Refer to ERRORS below for more infor- 

mation. 

EXAMPLES 

In the C programming language, the readmap, writemap, and exceptionmap parameters can be declared as 
int arrays. The size of the map arrays must be large enough to accommodate sdbound+1 bits. Thus, each 
map array must contain at least the following number of elements (where BITS_PER_INT is the number 
of bits in an int variable): 
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(sdbound + BITS_PER_INT) / BITS_PER_INT 

The bits can be set to correspond to specific call or VC socket descriptors in the appropriate map parameter. 
The following example can be used to set a bit in the array. (The socket descriptor is represented by the 
variable sd, and the number of bits in an int variable is 32.) 

readmap[sd/32] |= (unsigned) 0x80000000 >> (sd % 32); 

The next example can be used after an ipc select ( ) call completes to check whether or not a certain bit 
is set: 

readmaptsd/32] & ( (unsigned) 0x80000000 >> (sd % 32)) 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_BOUNDS_VIO] One of the pointer arguments is invalid. 

[NSR_DESC] A socket descriptor specified in a bitmap is not valid. 

[NSR_NO_ERROR] No error occured. 

[NSR_SIGNAL_INDICATION] A signal caused the call to abort. 

[NSR_SOCKET_TIMEOUT] The timer expired before an exception was detected. 

[NSR_TIMEOUT_VALUE] The value specified in the timeout parameter is invalid. 

AUTHOR 

ipcselect ( ) was developed by HP. 

SEE ALSO 

getrlimit(2), ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), 
ipcname(2), ipcnamerase(2), ipcrecv(2), ipcrecvcn(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), 
addopt(3N), initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcsend - send data on a NetlPC socket 

SYNOPSIS 

ttinclude <sys/ns_ipc.h> 

void ipcsend ( 

ns_int_t vcde.sc.- 
const void *data, 
ns_int_t dlen, 
ns_int_t * flags, 
short opt [ ] , 
ns_int_t *result); 

DESCRIPTION 

ipcsend ( ) is used to send data on an established connection. The data can be sent as a single contigu- 
ous buffer or as a scattered data vector. If the data is vectored, NetlPC gathers all the referenced data 
before sending it. 

For vectored writes an iovec structure contains the data vector. An iovec structure can be defined as: 

struct iovec { 

char *iov_base; 

unsigned iov_len; 
}; 

and the normal type for the data argument can be replaced by: 

struct iovec *data; 

Each iovec entry specifies the base address and length of an area in memory where data should be accessed, 
ipcsend ( ) always fills-in one area completely before proceeding to the next area. 

ipcsend ( ) behaves differently, depending on whether the referenced socket is in synchronous or asyn- 
chronous mode. These differences are as follows: 

Synchronous I/O. 

Send requests issued against sockets in synchronous mode may block, ipcsend () blocks if it cannot 
immediately obtain the buffer space needed to accommodate the data. The call resumes after the required 
buffer space becomes available or after the socket timer expires. Timeouts are 60 seconds by default, and 
can be altered by calling ipccontrol ( ) . 

Asynchronous I/O. 

Send requests issued against sockets in asynchronous mode never block. If the buffer space required to 
accommodate the data is not immediately available, a NSR_WOULD_BLOCK error (code 56) is returned. 
After receiving this error, the process can try the call again later or determine when the socket is writeable 
by calling ipcselect ( ) . 

PARAMETERS 

vcdesc (input parameter) Socket descriptor. Refers to the virtual circuit (VC) socket endpoint 

of the connection through which the data will be sent. A VC socket descriptor is 
obtained by calling ipcconnect ( ) or ipcrecvcn() . 

data (input parameter) A buffer to hold the data being sent, or a data vector that describes 

where the data to be sent is located. 

dlen (input parameter) lidata is a data buffer, dlen is the length in bytes of the data in the 

buffer. If data is a data vector, dlen is the length in bytes of the data vector. 

flags (input parameter) See below. 

opt (input parameter) An array of options and associated information. See below. 

result (output parameter) The error code returned. Refer to ERRORS below for more infor- 

mation. 

FLAGS PARAMETER 
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NSF_MORE_DATA (bit 26) (input parameter) When this bit is set, the underlying network protocol can 
temporarily delay sending data for efficiency reasons. 

NSF_VECTORED (bit 31) (input parameter) When this bit is set, the data parameter refers to a data 
vector and not to a data buffer. 



OPT PARAMETER 

NSO DATA OFFSET 



(optioncode =8) (datalength = 2) A two-byte integer that indicates a byte offset from 
the beginning of the data buffer where the data to be sent actually begins. Only valid 
if the data parameter is a data buffer. 



RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 



[NSR_BOUNDS_VIO] 

[NSR.DESC] 

[NSR_DLEN] 

[NSR_DUP_OPTION] 

[NSR.FLAGS] 

[NSR.MSGSIZE] 



An address parameter is invalid. 

The vcde.sc parameter is not a valid descriptor. 

The value specified in the dlen parameter is invalid. 

The opt array contains duplicate information. 

An illegal flag was specified. 

An illegal data length was specified. By default, data transfer is limited to 
a 100 byte maximum. You can alter this limit by calling ipccontrol ( ) 



[NSR_NOT_CONNECTION] 

[NSR_OPT_OPTION] 

[NSR_OPT_SYNTAX] 

[NSR_SIGNAL_INDICATION] 

[NSR_SOCKET_TIMEOUT] 



The vcdesc parameter is not a valid VC socket. 

An option in the opt parameter in unknown or invalid. 

A length or offset value in the opt parameter is invalid. 

The call aborted due to a signal. 

The socket timer expired before the data could be transfered. By default, 
the socket timer is 60 seconds. This value can be altered by calling 
ipccontrol ( ) . 

The maximum number of data vectors was exceeded. The limit is 16. 

An incorrect data length was specified for vectored data. 

The requested data cannot be sent at this time. 



[NSR_TOO_MANY_VECTS] 

[NSR_VECT_COUNT] 

[NSR_WOULD_BLOCK] 

AUTHOR 

ipcsend ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcsetnodename - set NetlPC node name of host CPU 

SYNOPSIS 

ttinclude <sys/ns_ipc.h> 

void ipcsetnodename ( 

const char *nodename, 
ns_int_t namelen, 
ns_int_t *result); 

DESCRIPTION 

ipcsetnodename ( ) sets the NetlPC node name of the host processor to nodename, which has a length of 
namelen characters. 

Super-user capability is required to use this call. 

Parameters 

nodename (input parameter) The ASCII-coded name that is to be assigned to this host. 

namelen (output parameter) The length in bytes of the nodename parameter. 
result (output parameter) See ERRORS below. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

AUTHOR 

ipcsetnodname was developed by HP. 

ERRORS 

[NSR_NO_ERROR] The call was successful. 

[NSR_NOT_ALLOWED] The caller does not have super-user capability. 

[NSR_BOUNDS_VIO] The input parameter address is invalid. 

[NSR_NLEN] The value of the namelen parameter is invalid. 

[NSR_NODE_NAME_SYNTAX] The syntax of the nodename parameter is illegal. 

AUTHOR 

ipcsetnodename ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcshutdown(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

ipcshutdown - release a NetlPC descriptor 

SYNOPSIS 

#include <sys/ns_ipc.h> 

void ipcshutdown ( 

ns_int_t descriptor, 
ns_int_t *flags, 
short opt [ ] , 
ns_int_t *resuit); 
DESCRIPTION 

ipcshutdown ( ) is used to release a descriptor. The referenced descriptor can be a call socket descriptor, 
virtual circuit (VC) socket descriptor, or destination descriptor. Once a descriptor has been realeased, the 
descriptor can no longer be used by the calling process. Since the descriptor may be shared between 
processes, it is destroyed only if the calling process is the last process referencing it. 

When a call socket, VC socket, or destination descriptor is destroyed, all resources are released and the 
descriptor name(s) in the local socket registry are removed. Shutting down a VC socket does not affect any 
call sockets, and shutting down a call socket does not affect any VC sockets created using the call socket. 
All of the data in transit on a VC socket, including any data that has already been queued on the destina- 
tion VC socket, may be destroyed when the connection is shut down unless the 
NSF_6RACEPUL_RELEASE flag is set. If a process sends important data to its peer process just prior to 
shutting that process down, it is recommended that the calling process receive a confirmation from the peer 
process before calling ipcshutdown () or exiting, or use the NSP_6RACEPUL_RELEASE flag to ensure 
that the data was received. 
PARAMETERS 

descriptor (input parameter) The descriptor to be released. Can be a call socket descriptor, VC 

socket descriptor, or destination descriptor. 
flags (input parameter) Must be or NSP_6RACEPUL_RELEASE. See below. 

opt (input parameter) No options are defined for -this call. Can be or a pointer to an 

empty NetlPC option buffer. 
result (output parameter) The error code returned. Refer to ERRORS below for more infor- 

mation. 
Flags Parameter 

NSP_GRACEPUL_RELEASE 

If this flag is set, the underlying network protocol can continue to transmit data after 
the calling process exits. 
RETURN VALUE 

None. Errors are returned to the result parameter. 
ERRORS 

[NSRJDESC] The descriptor parameter is not a valid VC socket descriptor, call socket descriptor, or 

destination descriptor. 
[NSR_FLAGS] The flags parameter is illegal or unsupported. 

[NSR_NO_ERROR] The call was successful. 
[NSR_OPT_OPTION] An unsupported option was specified. 

[NSR_OPT_SYNTAX] A length or offset within the opt parameter is invalid or unsupported. 
AUTHOR 

ipcshutdown ( ) was developed by HP. 
SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), addopt(3N), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME 

kill, raise - send a signal to a process or a group of processes 

SYNOPSIS 

ttinclude <signal.h> 

int kill(pid_t pid, int sig); 
int raise(int sig); 

DESCRIPTION 

ki 1 1 ( ) sends a signal to a process or a group of processes. The process or group of processes to which the 
signal is to be sent is specified by pid. The signal to be sent is specified by sig and is either one from the list 
given in signal{2), or 0. 

raise ( ) sends signal sig to the executing program. The signal to be sent is specified by sig and is either 
one from the fist given in signal(2), or 0. 

If sig is (the null signal), error checking is performed but no signal is actually sent. This can be used to 
check the validity of pid. 

The real or effective user ID of the sending process must match the real or saved user ID of the receiving 
process unless the effective user ID of the sending process is a user who has appropriate privileges. As a 
single special case, the continue signal SIGCONT can be sent to any process that is a member of the same 
session as the sending process. 

The value KILL_ALL_OTHERS is defined in the file <sys /signal .h> and is guaranteed not to be the 
ID of any process in the system or the negation of the ID of any process in the system. 

Ifpid is greater than zero and not equal to KILL_ALL_OTHERS, sig is sent to the process whose process ID 
is equal to pid. pid can equal 1 unless sig is SIGKILL or SIGSTOP . 

lipid is 0, sig is sent to all processes excluding special system processes whose process group ID is equal to 
the process group ID of the sender. 

If pid is -1 and the effective user ID of the sender is not a user who has appropriate privileges, sig is sent 
to all processes excluding special system processes whose real or saved user ID is equal to the real or 
effective user ID of the sender. 

If pid is - 1 and the effective user ID of the sender is a user who has appropriate privileges, sig is sent to all 
processes excluding special system processes. 

If pid is KILL_ALL_OTHERS, kill ( ) behaves much as when pid is equal to -1, except that sig is not 
sent to the calling process. 

If pid is negative but not -1 or KILL_ALL_OTHERS, sig is sent to all processes (excluding special system 
processes) whose process group ID is equal to the absolute value of pid, and whose real and/or effective user 
ID meets the constraints described above for matching user IDs. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

ki 11 ( ) fails and no signal is sent if one or more of the following is true: 

[EINVAL] sig is neither a valid signal number nor zero. 

[EINVAL] sig is SIGKILL or SIGSTOP and pid is 1 (procl). 

[EPERM] The user ID of the sending process is not a user who has appropriate privileges and its 

real or effective user ID does not match the real or saved user ID of the receiving pro- 
cess. 

[EPERM] The sending and receiving processes are not in the same session. 

[ESRCH] No process or process group can be found corresponding to that specified by pid. 

raise ( ) fails and no signal is sent if the following is true: 
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[EINVAL] sig is not a valid signal number or zero. 

AUTHOR 

kill ( ) was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO 

kill(l), getpid(2), setpgrp(2), signal(2), privilege(5). 

STANDARDS CONFORMANCE 

kill ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l 

raise ( ) : AES, XPG4, ANSI C 
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~~ NAME 

link - link to a file 

SYNOPSIS 

#include <unistd.h> 

int link (const char *pathl, const char *path2); 

DESCRIPTION 

link ( ) creates a new link (directory entry) for the existing file, pathl points to a path name naming an 
existing file. path2 points to a path name naming the new directory entry to he created. 

RETURN VALUE 

Upon successful completion, link ( ) returns 0; otherwise, it returns -1 and sets errno to indicate the 



I 



ERRORS 

link ( ) fails and no link is created if one or more of the following is true: 



[EACCES] 
[EACCESJ 

[EDQUOT] 

[EEXISTJ 

[ENOENT] 

[ENOENT] 

[ENOENT] 

[ENOSPCJ 

[ENOTDIR] 

[EPERM] 

[EXDEV] 

[EROFS] 

[EFAULT] 

[ENOENT] 
[EMLINK] 
[ENAMETOOLONG] 

[ELOOP] 



A component of either path prefix denies search permission. 

The requested link requires writing in a directory that does not permit 
writing. 

User's disk quota block limit has been reached for this file system. 

The link named by path2 exists. 

The file named by pathl does not exist. 

A component of either path prefix does not exist. 

path2 points to a null path name. 

The directory to contain the file cannot be extended. 

A component of either path prefix is not a directory. 

The file named by pathl is a directory and the effective user ID is not a 
user who has appropriate privileges. 

The link named by path2 and the file named by pathl are on different logi- 
cal devices (file systems). 

The requested link requires writing in a directory on a read-only file sys- 
tem. 

path points outside the allocated address space of the process. The reliable 
detection of this error is implementation dependent. 

pathl or path2 is null. 

The maximum number of links to a file would be exceeded. 

Either specified path exceeds PATH_MAX bytes, or a component of either 
specified path exceeds NAME_MAX while POSIX_NO_TRUNC is in effect. 

Too many symbolic links were encountered in translating either path 
name. 



DEPENDENCIES 

Series 300, 400, and 700: 

\ipath2 names a symbolic link, link ( ) fails without creating the link, -1 is returned, and errno is set 
to: 

[EEXIST] path2 names a symbolic link. 

SEE ALSO 

cp(l), link(lM), symlink(2), symlink(4), unlink(2). 

STANDARDS CONFORMANCE 

link ( ) : AES [Series 300/400/700 only], SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

listen - listen for connections on a socket 

SYNOPSIS 

int listen(int s, int backlog); 

DESCRIPTION 

To accept connections, a socket is first created using socket ( ) , a queue for incoming connections is 
specified using listen(), and then connections are accepted using accept (). listen () applies 
only to unconnected sockets of type SOCK_STREAM. If the socket has not been bound to a local port before 
listen ( ) is invoked, the system automatically binds a local port for the socket to listen on (see inet(7F)). 
For sockets in the address family AF_CCITT, the socket must be bound to an address by using bind ( ) 
before connection establishment can continue, otherwise an EADDREQUIRED error is returned. 

The listen queue is established for the socket specified by the s parameter, which is a socket descriptor. 

backlog defines the maximum allowable length of the queue for pending connections. If a connection 
request arrives when the queue is full, the client receives an ETIMEDOUT error. 

backlog is currently limited (silently) to be in the range of 1 to 20. If any other value is specified, the system 
automatically assigns the closest value within range. 

DEPENDENCIES 
AF.CCITT: 

Call-acceptance can be controlled by the X2 5_CALL_ACPT_APPROVAL ioctl() call described in 
RETURN VALUE Upon successful completion, listenO returns 0; otherwise, it returns -1 and sets 
errno to indicate the error. 

ERRORS 

listen ( ) fails if any of the following conditions are encountered: 

[EBADF] The argument s is not a valid descriptor. 

[EDESTADRREQ] No bind address was established. 

[ENOTSOCK] The argument s is not a socket. 

[EOPNOTSUPP] The socket is not of a type that supports the 1 i s t en ( ) operation. 

[ENOBUFS] (Series 300/400 only) No buffer space is available. listen () cannot be 

started at this time. 

[EINVAL] The socket has been shut down or is already connected (see socketx25(7)). 

AUTHOR 

listen ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

accept(2), connect(2), socket(2), socketx25(7), af_ccitt(7F), inet(7F). 



I 



HP-UX Release 9.0: August 1992 - 1 - 115 



I 



#define 


P ULOCK 





/ 


#define 


P_LOCK 


1 


/ 


#define 


P_TLOCK 


2 


/ 


#define 


P_TEST 


3 


/ 



lockf(2) lockf(2) 



NAME 

lockf - provide semaphores and record locking on files 

SYNOPSIS 

#include <unistd.h> 

int lockf (int fildes, int function, off_t size); 

DESCRIPTION 

lockf ( ) allows regions of a file to be used as semaphores (advisory locks) or restricts access to only the 
locking process (enforcement-mode record locks). Other processes that attempt to access the locked resource 
either return an error or sleep until the resource becomes unlocked. All locks for a process are released 
upon the first close of the file, even if the process still has the file opened, and all locks held by a process are 
released when the process terminates. 

fildes is an open file descriptor. The file descriptor must have been opened with write-only permission 
(0_WRONLY) or read-write permission (0_RDWR) in order to establish a lock with this function call (see 
open. (2)). 

If the calling process is a member of a group that has the PRIV_LOCKRDONLY privilege (see set- 
privgrp{2)), it can also use lockf ( ) to lock files opened with read-only permission (0_RDONLY). 

function is a control value that specifies the action to be taken. Permissible values for function are defined 
in <unistd.h> as follows: 

unlock a region */ 
lock a region */ 
test and lock a region */ 
test region for lock */ 

All other values of function are reserved for future extensions and result in an error return if not imple- 
mented. 

F_TEST is used to detect whether a lock by another process is present on the specified region, lockf ( ) 
returns zero if the region is accessible and -1 if it is not; in this case errno is set to EACCES. P_LOCK 
and F_TLOCK both lock a region of a file if the region is available. F_ULOCK removes locks from a 
region of the file. 

size is the number of contiguous bytes to be locked or unlocked. The resource to be locked starts at the 
current offset in the file, and extends forward for a positive size, and backward for a negative size (the 
preceding bytes up to but not including the current offset). If size is zero, the region from the current offset 
through the end of the largest possible file is locked (that is, from the current offset through the present or 
any future end-of-file). An area need not be allocated to the file in order to be locked, because such locks can 
exist past the end of the file. 

Regions locked with F_LOCK or F_TLOCK can, in whole or in part, contain or be contained by a previ- 
ously locked region for the same process. When this occurs or if adjacent regions occur, the regions are com- 
bined into a single region. If the request requires that a new element be added to the table of active locks 
but the table is already full, an error is returned, and the new region is not locked. 

F_LOCK and F__TLOCK requests differ only by the action taken if the resource is not available: F_LOCK 
causes the calling process to sleep until the resource is available, whereas F_TLOCK returns an EACCES 
error if the region is already locked by another process. 

F__ULOCK requests can, in whole or part, release one or more locked regions controlled by the process. 
When regions are not fully released, the remaining regions are still locked by the process. Releasing the 
center section of a locked region requires ah additional element in the table of active locks. If this table is 
full, an EDEADLK error is returned, and the requested region is not released. 

Regular files with the file mode of S_ENFMT, not having the group execute bit set, will have an enforcement 
policy enabled. With enforcement enabled, reads and writes that would access a locked region sleep until 
the entire region is available if 0_NDELAY is clear, but return -1 with errno set if 0_NDELAY is set. 
File access by other system functions, such as exec ( ) , are not subject to the enforcement policy. Locks on 
directories, pipes, and special files are advisory only; no enforcement policy is used. 

A potential for deadlock occurs if a process controlling a locked resource is put to sleep by accessing the 
locked resource of another process. Thus, calls to fcntl(), lockf (), read(), or write () (see 
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fcntl(2), lockf(2), read(2), and write(2)) scan for a deadlock prior to sleeping on a locked resource. Deadlock 
is not checked for the wait ( ) and pause ( ) system calls (see wait{2) and pause{2)), so potential for 
deadlock is not eliminated. A creat() call or an open() call with the 0_CREATE and 0_TRUNC 
flags set on a regular file returns error EAGAIN if another process has locked part of the file and the file is 
currently in enforcement mode. 

NETWORKING FEATURES 

NFS 

The advisory record-locking capabilities of lockf ( ) are implemented throughout the network by the "net- 
work lock daemon" (see lockdOM)). If the file server crashes and is rebooted, the lock daemon attempts to 
recover all locks associated with the crashed server. If a lock cannot be reclaimed, the process that held the 
lock is issued a SIGLOST signal. 

Only advisory record locking is implemented for NFS files. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

lockf ( ) fails if any of the following occur: 

[EACCES] function is F_TLOCK or F_TEST and the region is already locked by another pro- 

cess. 

[EBADF] fildes is not a valid, open file descriptor. 

[EDEADLK] A deadlock would occur or the number of entries in the system lock table would 
exceed a system-dependent maximum. HP-UX guarantees this value to be at least 50. 

[EAGAIN] function is F_LOCK or F_TLOCK and the file is mapped in to virtual memory via 

the mmap ( ) system call (see mmap(2)). 

[EINTR] A signal was caught during the lockf ( ) system call. 

[EINVAL] function is not one of the functions specified above. 

[EINVAL] size plus current offset produces a negative offset into the file. 

[ENOLCK] function is F_TLOCK or F_LOCK and the file is an NFS file with access bits set for 

enforcement mode. 

[ENOLCK] The file is an NFS file and a system error occurred on the remote node. 

WARNINGS 

Deadlock conditions may arise when either the wait ( ) or pause ( ) system calls are used in conjunction 
with enforced locking; see wait(2) and pause(2) for details. 

File and record locking using file descriptors obtained through dup() or link() may not work as 
expected (see dup(2) or link(2)). For example, unlocking regions that were locked using either file descrip- 
tor may also unlock regions that were locked using the other file descriptor. 

Unexpected results may occur in processes that use buffers in the user address space. The process may 
later read or write data which is or was locked. The standard I/O package, stdio(SS), is the most common 
source of unexpected buffering. 

In a hostile environment, locking can be misused by holding key public resources locked. This is particu- 
larly true with public read files that have enforcement enabled. 

It is not recommended that the PRIV_LOCKRDONLY capability be used because it is provided for back- 
ward compatibility only. This feature may be modified or dropped from future HP-UX releases. 

Locks default to advisory mode unless the set gid bit of the file permissions is set. 

APPLICATION USAGE 

Because in the future the variable errno will be set to EAGAIN rather than EACCES when a section of a 
file is already locked by another process, portable application programs should expect and test for either 
value. For example: 
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if (lockf(fd, F_TLOCK, siz) == -1) 

if ((errno == EAGAIN) I I (errno == ACCES) ) 
/* 

* section locked by another process 

* check for either EAGAIN or EACCES 

* due to different implementations 
*/ 

else if ... 
/* 

* check for other errors 
*/ 

SEE ALSO 

iockd(lM), statd(lM), chmod(2), close(2), creat(2), fcntl(2), open(2), pause(2), read(2), stat(2), wait(2), 
write(2), unistd(5). 

FUTURE DIRECTIONS 

The error condition that currently sets errno to EACCES will instead set errno to EAGAIN (see also 
APPLICATION USAGE above). 

STANDARDS CONFORMANCE 

lockf ( ) : SVID2, XPG2 



I 
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NAME 

lseek - move read/write file pointer; seek 

SYNOPSIS 

#include <unistd.h> 

off_t lseek(lnt fildes, off_t offset, int whence); 

DESCRIPTION 

lseek ( ) sets the file pointer associated with the file descriptor as follows: 

• If whence is 3EEK_SET, the pointer is set to offset bytes. 

• If whence is SEEK_CUR, the pointer is set to its current location plus offset. 

• If whence is SEEK_END, the pointer is set to the size of the file plus offset. 
These symbolic constants are defined in <unistd . h>. 

RETURN VALUE 

When lseek ( ) completes successfully, it returns an integer, which is the resulting file offset as measured 
in bytes from the beginning of the file. Otherwise, a value of -1 is returned and errno is set to indicate 
the error. 

For all files that are not character or block special files, the integer returned on successful completion is 
non-negative. For character or block special files that correspond to disk sections larger than 2 gigabytes, a 
non-negative integer is returned for successful seeks beyond 2 gigabytes. This value is the resulting file _ 

offset as measured in bytes from the beginning of the file, when taken as an unsigned value. -1 always I 

indicates an error return, even when encountered on greater than 2 gigabyte disk sections. ■ 

ERRORS 

lseek ( ) fails and the file offset remains unchanged if one or more of the following is true: 

[EBADF] fildes is not an open file descriptor. 

[ESPIPE] fildes is associated with a pipe or FIFO. 

[EINVAL] whence is not one of the supported values. 

[EINVAL] The resulting file offset would be negative. 

WARNINGS 

Some devices are incapable of seeking. The value of the file offset associated with such a device is 
undefined. 

Using lseek ( ) with a whence of SEEK_END on device special files is not supported and the results are 
not defined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), open(2), unistd(5). 

STANDARDS CONFORMANCE 

lseek ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

madvise - advise the system of a process' expected paging behavior 

SYNOPSIS 

#include <sys/inman.h> 

int madvise ( 

caddr_t addr, 
size_t len, 
int behav ) ; 

DESCRIPTION 

madvise permits a process to advise the system about its expected future behavior in referencing a 
mapped file or a: 
use of resources. 

addr and len specify the address and length in bytes of the region to which the advice refers. If these are 
not the address and length of a region created by a successful call to mmap ( ) , madvise ( ) fails with an 
EINVAL error. 

The behav argument is constructed from the bitwise inclusive OR of one or more of the following flags 
defined in the header <sys /mman . h>: 

MADV_NORMAL No further special treatment. 

MADV_RANDOM Expect random page references. 

MADV_SEQUENTIAL Expect sequential page references. 

MADV_WILLNEED Will need these pages. 

MADV_DONTNEED Will not need these pages. 

MADVJSPACEAVAIL Ensure that resources are reserved. 

IMPLEMENTATION NOTES 

The current implementation of madvise ( ) is a null operation. 

RETURN VALUE 

madvise ( ) returns upon success; otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

madvise ( ) fails if any of the following conditions are encountered: 

[EFAULT] The range specified by {addr, addr+len) is invalid for a process' address space. 

[EINVAL] addr is not a multiple of the page size as returned by 

sysconf (_SC_PAGE_SIZE), or behav contains invalid values or incompatible 
combinations of flags. 

[EINVAL] The address range specified by addr and len was not created by a successful call to 

mmap ( ) . 

AUTHOR 

madvise ( ) was developed by HP and OSF. 

SEE ALSO 

mmap(2), sysconf(2). 

STANDARDS CONFORMANCE 

madvise ( ) : AES 
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NAME 

mkdir - make a directory file 

SYNOPSIS 

ttinclude <sys/stat.h> 

int mkdir (const char *path, mode_t mode); 

DESCRIPTION 

mkdir ( ) creates a new directory file named by path. The file permission bits of the new directory are ini- 
tialized from mode, and are modified by the process's file mode creation mask. For each bit set in the 
process's file mode creation mask, the corresponding bit in the new directory's mode is cleared (see 
umask{2)). 

The directory's owner ID is set to the process's eflfective-user-ID. If the set-group-ID bit of the parent direc- 
tory is set, the directory's group ID is set to group ID of the parent directory. Otherwise, the directory's 
group ID is set to the process's efifective-group-ID. The set-group-ID bit of the new directory is set to the 
same value as the set-group-ID bit of the parent directory. 

Symbolic constants defining the access permission bits are found in the <sys/stat .h> header and are 
used to construct the argument mode. The value of the argument mode is the bit-wise inclusive OR of the 
values of the desired permissions. 

S_IRUSR Read by owner. 

S_IWUSR Write by owner. 

S_IXUSR Execute (search) by owner. 

S_IRGRP Read by group. 

S_IWGRP Write by group. 

S_IXGRP Execute (search) by group. 

S_IROTH Read by others (that is, anybody else). 

S_IWOTH Write by others. 

S_IXOTH Execute (search) by others. 

Access Control Lists (ACLs) 

On systems implementing access control lists, the directory is created with three base ACL entries, 
corresponding to the file access permission bits (see ac/(5)). 

RETURN VALUE 

Upon successful completion, mkdir ( ) returns a value of 0; a return value of -1 indicates an error, and 
an error code is stored in errno. 

ERRORS 

mkdir ( ) fails and no directory is created if any of the following is true: 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] The parent directory of the new directory denies write permission. 

[EEXIST] The named file already exists. 

[EFAULT] path points outside the process's allocated address space. The reliable detection of this 

error is implementation dependent. 

[EIO] An I/O error occurred while writing to the file system. 

[ELOOP] Too many symbolic links are encountered in translating the path name. 

[EMLINK] The maximum number of links to the parent directory, { LINK_MAX } , would be exceeded. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a com- 
ponent of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in 
effect. 

[ENOENT] A component of the path prefix does not exist. 

[ENOSPC] Not enough space on the file system. 
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[ENOTDIR] A component of the path prefix is not a directory. 

[EROFS] The named file resides on a read-only file system. 

[EDQUOT] User's disk quota block or inode limit has been reached for this file system. 

WARNINGS 

Access Control Lists 

Access control fist descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

AUTHOR 

mkdir ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

chmod(2), setacl(2), stat(2), umask(2), acl(5), limits(5). 

STANDARDS CONFORMANCE 

mkdir ( ) : AES, SVID2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

mknod, mkrnod - make a directory, or a special or regular file 

SYNOPSIS 

ttinclude <sys/stat.h> 

int mknod (const char *path / mode_t mode, dev_t dev) ; 

int mkrnod ( 

const char *path, 



dev_t dev, 
cnode t cnodeid 



); 



DESCRIPTION 

mknod ( ) creates a new file named by the path name pointed to by path. The mode of the new file is 
specified by the mode argument, mkrnod ( ) is the same as mknod ( ) but is used to make device files 
that can be accessed from a different cnode in the cluster as identified by the additional parameter cnodeid. 
A cnodeid value of creates a "generic" device file that can be accessed by any cnode. 

Symbolic constants defining the file type and file access permission bits are found in the <sys/stat .h> 
header file and are used to construct the mode argument. The value of the mode argument should be the 
bit-wise inclusive OR of the values of the desired file type, miscellaneous mode bits, and access permissions. 
See stat(5) for a description of the components of the file mode. 

The owner ID of the file is set to the efFective-user-ID of the process. If the set-group-ID bit of the parent 
directory is set, the new file's group ID is set to the group ID of the parent directory. Otherwise, the new 
file's group ID is set to the effective-group-ID of the process. 

The file access permission bits of mode are modified by the process's file mode creation mask: for each bit 
set in the process's file mode creation mask, the corresponding bit in the file's mode is cleared (see 
umask(2)). 

The new file is created with three base access-control-list (ACL) entries, corresponding to the file access per- 
mission bits (see acl(5)). 

The dev argument is meaningful only if mode indicates a block or character special file, and is ignored oth- 
erwise. It is an implementation- and configuration-dependent specification of a character or block I/O dev- 
ice. The value of dev is created by using the makedev ( ) macro defined in <sys /mknod . h>. The mak- 
edev ( ) macro takes as arguments the major and minor device numbers, and returns a device 
identification number which is of type dev_t. The value and interpretation of the major and minor device 
numbers are implementation-dependent. For more information, see mknod(5) and the System Administra- 
tion manuals for your system. 

Only users having appropriate privileges can invoke mknod ( ) for file types other than FIFO files. 

WARNINGS 

Proper discretion should be used when using mkrnod ( ) to create generic device files in an HP Clustered 
Environment. A generic device file accessed from different cnodes in a cluster applies to different physical 
devices. Thus the file's ownership and permissions might not be appropriate in the context of every indivi- 
dual cnode in the cluster. 

RETURN VALUE 

Upon successful completion a value of is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

mknod ( ) fails and the new file is not created if: 

[EACCES] The directory in which path would be created denies write permission, mode is for a 

FIFO file and the caller does not have appropriate privileges. 

[EACCES] A component of the path prefix denies search permission. 

[EEXIST] The named path already exists. 
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DEFAULT] The path argument points outside the process's allocated address space. The reliable 

detection of this error is implementation dependent. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 



[ENOENT] 

[ENOENT] 

[ENOSPC] 

[ENOTDIR] 

[EPERM] 

[EROFS] 
[EDQUOT] 



The path argument is null. 

A component of the path prefix does not exist. 



_ j-i-_ a\. 



JNot enougii space on me me system. 

A component of the path prefix is not a directory. 

The effective-user-ID of the process does not match that of a user who has appropriate 
privileges, and the file type is not FIFO special. 

The directory in which the file is to be created is located on a read-only file system. 

User's disk quota block or inode limit has been reached for this file system. 



I 



AUTHOR 

mknod ( ) was developed by AT&T and HP. 

SEE ALSO 

mknod(lM), chmod(2), exec(2), mkdir(2), setacl(2), umask(2), cdf(4), fs(4), acl(5), mknod(5), stat(5), types(5), 
privilege(5). 

STANDARDS CONFORMANCE 

mknod():SVID2,XPG2 
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NAME 

mmap - map object into virtual memory 

SYNOPSIS 

ttinclude <sys/raman.h> 

caddr_t mmap ( 

caddr_t addr, 
size_t len, 
int prot, 
int flags, 
int fildes, 
off_t off); 

DESCRIPTION 

mmap ( ) creates a new memory mapped file or anonymous memory region. The format of the call is as fol- 
lows: 

pa = mmap( addr , len, prot, flags , fildes, off) ; 

mmap ( ) establishes a mapping between the process's address space at an address pa for len bytes to an 
object represented by the file descriptor fildes at offset off for len bytes, or to an anonymous region of physi- 
cal memory of size len bytes. A successful mmap ( ) call returns pa as its result, where pa is an 
implementation-dependent function of the requested starting address and length for the new region, addr 
and len, as further described below. 

If len is not a multiple of the page size returned by sysconf (_SC_PAGE_SIZE), then references are 
permitted to an address between pa +len and the next higher address that is an integer multiple of the page 
size; however, the results of any such references are undefined. 

The flags argument specifies the attributes of the region. Values of the flags argument are constructed by 
bitwise-inclusive ORing flags from the following list of symbolic names defined in <sys /mman . h>: 

MAP_PILE Create a mapped file region. 

MAP_ANONYMOUS Create an unnamed memory region. 

MAP_VARIABLE Place region at implementation-computed address. 

MAP_FIXED Place region at specified address. 

MAP_SHARED Share changes between processes and underlying file object, if any. 

MAP_PRIVATE Changes are private to a process. 

The MAP_FILE and MAP_ANONYMOUS flags control whether the region to be mapped is a mapped file 
region or an anonymous shared memory region. Exactly one of these flags must be selected. 

If MAP_PILE is set in /fags: 

• A new mapped file region is created, mapping the file associated with fildes. 

• off specifies the file byte offset at which the mapping starts. This offset must be a multiple of the 
page size returned by sysconf (_SC_PAGE_SIZE ) . 

• If the end of the mapped file region is beyond the end of the file, any reference to an address in 
the mapped file region corresponding to an offset beyond the end of the file results in the delivery 
of a SIGBUS signal to the process, unless the address lies in the last partial page corresponding 
to the range beyond the end of the file. The last partial page mapping the range beyond the end 
of the file is always initialized to zeros, and any modified portions of the last page of a file which 
are beyond its end are not written back to the file. 

If MAP_ANONYMOUS is set in flags: 

• A new memory region is created and initialized to all zeros. This memory region can be shared 
only with descendants of the current process. 

• If the fildes argument is not -1, an EINVAL error is generated. 
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• The value of off is meaningless because there is no underlying file object for the memory region. 

The MAP_VARIABLE and MAP_PIXED flags control the placement of the region as described below. 
Exactly one of these flags must be selected. 

If MAP_VARIABLE is set in flags: 

• If the requested address is NULL, or if it is not possible for the system to place the region at the 
requested address, the region is placed at an address selected by the system. If the requested 
address is not a multiple of the page size returned by sysconf (_SC_PAGE_SIZE), the sys- 
tem treats the address as if it were rounded up to the next larger page size multiple. 

If MAP_P IXED is set in flags : 

• If it is not possible for the system to place the region at the requested address, the inmap ( ) 
function fails. 

• addr must be a multiple of the page size returned by sysconf (_SC_PAGE_SIZE ) . 

A region is never placed at an address where it would overlap with an existing region or a portion of the 
process address space that is already in use or reserved for other purposes. A region is always placed at a 
starting address that is an exact multiple of the page size returned by sysconf (_SC_PAGE_SIZE) . 

The MAP_PRIVATE and MAP_SHARED flags control the visibility of modifications to the mapped file or 
anonymous memory region. Exactly one of these flags must be selected. 

If MAP_SHARED is set in flags: 

• Modifications to the region are visible to other processes which have mapped the same file using 
MAP_SHARED. 

• If the region is a mapped file region, modifications to the region are written to the underlying 
file. 

If MAP_PRIVATE is set in flags: 

• Modification to the mapped region by the calling process is not visible to other processes which 
have mapped the same region using either MAP_PRIVATE or MAP_SHARED. Modifications are 
not visible to descendant processes that have inherited the mapped region across a fork ( ) . 

• If the region is a mapped file region, modifications to to the region are not written to the underly- 
ing file. 

It is unspecified whether modifications by processes that have mapped a file using MAP_SHARED are visi- 
ble to other processes that have mapped the same file usingMAP_PRIVATE. 

The prat argument specifies the mapped region's access permissions. Header file <sys/inman.h> defines 
the following access permissions: 

PROT_READ Region can be read 

PROT_WRITE Region can be written 

PROT_EXEC Region can be executed 

PROT_NONE Region cannot be accessed 

The prot argument can be PROTJNONE, or any combination of PROT_READ, PROT_WRITE , and 
PROT_EXEC OR-ed together. If PROT_NONE is not specified, the system may grant other access permis- 
sions to the region in addition to those explicitly requested, except that write access will not be granted 
unless PROT_WRITE is specified. 

mmap ( ) cannot create a mapped file region unless the file descriptor used to map the file is open for read- 
ing. For a mapped file region that is mapped with MAP_SHARED, mmap ( ) grants write access permission 
only if the file descriptor is open for writing. If a region was mapped with either MAP_PRIVATE or 
MAP_ANONYMOUS, mmap ( ) grants all requested access permissions. 

After the successful completion of mmap ( ) , fildes can be closed without effect on the mapped region or on 
the contents of the mapped file. Each mapped region creates a file reference, similar to an open file descrip- 
tor, that prevents the file data from being deallocated. 

Whether modifications made to the file using write () are visible to mapped regions, and whether 
modification to a mapped region are visible with read ( ) , is undefined except for the effect of ntsync ( ) . 

126 - 2 - HP-UX Release 9.0: August 1992 



mmap(2) mmap(2) 



If an enforcement-mode file lock is in effect for any range of a file, a call to mmap ( ) to map any range of 
the file with access rights that would violate the lock fails. The msem_lock ( ) and msem_unlock ( ) 
semaphore interfaces can be used to coordinate shared access to a region created with the MAP_SHARED 
flag. The advisory locks of the lockf ( ) or fcntl() interfaces have no effect on memory mapped 
access, but they can be used to coordinate shared access to a MAP_SHARED mapped file region. 

For a memory mapped file, the st_atime and st_mtime values returned by stat () are updated 
when a page in the memory mapped region is read from or written to the file system. 

After a call to fork ( ) , the child process inherits all mapped regions with the same data and the same 
sharing and protection attributes as in the parent process. Each mapped file and anonymous memory 
region created with mmap ( ) is unmapped upon process exit, and by a successful call to any of the exec 
functions. 

A SIGBUS signal is delivered to a process when a write reference to a mapped file region would cause a file 
system error condition such as exceeding quota or file system space limits. 

A SIGBUS signal is delivered to a process upon a write reference to a region without PROT_WRITE pro- 
tection, or any reference to a region with PROT_NONE protection. 

A call to mmapO with PROT_EXECUTE specified, but without PROTJ9RITE specified for a 
MAP_SHARED |MAP_PILE mapping is treated by the system as the execution of the underlying file. This 
implies that such a call fails if the file is currently open for writing or mapped with 
MAP_SHARED I PROTJWRITE options by any process, and that if the call succeeds, the file cannot be 
opened for writing or subsequently mapped with MAP_SHARED I PROT_WRITE options as long as such 
mappings are present. A file's status as an active executable file is determined only at the time of an 
exec (), exit (), or mmap () operation. mprotect() operations on a MAP_FILE|MAP_SHARED 
mapping have no effect on the underlying file's status as an active executable file. 

IMPLEMENTATION NOTES 

Only regular files (not directories, named pipes, or device special files) can be mapped. 

System swap resources are reserved for all mappings created with either MAP_PRIVATE or 
MAP_ANONYMOUS. 

RETURN VALUE 

Upon successful completion, mmap ( ) returns the address at which the mapping was placed. Otherwise, 
mmap ( ) returns -1 and sets errno to indicate the error. 

ERRORS 

mmap ( ) fails if any of the following conditions are encountered: 

[EACCESS] The file referred to by fildes is not open for read access, or the file is not open for write 

access and PROTJWRITE was set for a MAP_SHARED mapping operation, or 
PROT_EXECUTE was set for a MAP_SHARED mapping operation and the underlying 
file does not have execute permission. 

[EBADF] fildes is not a valid file descriptor. 

[EINVAL] flags or prot is invalid, or addr (with MAP_FIXED set) or off(yrith MAP_PILE set) is 

not a multiple of the page size returned by sysconf (_SC_PAGE_SIZE ) . 

[ENODEV] fildes refers to an object that cannot be mapped, such as a terminal. 

[ENOMEM] There is not enough address space to map len bytes, or MAP_FIXED was set and 

part of the address space range [addr, addr+len) (from, and including, addr to, but 
not including, addr+len) is not available for use. 

[ENXIO] The addresses specified by the range [off, off+len) (from, and including, off to, but not 

including, off+len) are invalid for fildes. 

[EAGAIN] The file represented by fildes has enforcement-mode file locking in effect for some 

range in the file, (see lockf(2), or fcntl(2)). 

[ETXTBSY] MAP_SHARED and MAP_PILE are set, and PROT_EXECUTE is set and 

PROT_WRITE is not set, and the file being mapped is currently open for writing. 
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DEPENDENCIES 
Series 700/800 

Because the PA-RISC memory architecture utilizes a globally shared virtual address space between 
processes, and discourages multiple virtual address translations to the same physical address, all con- 
currently existing MAP_SHARED mappings of a file range must share the same virtual address offsets and 
hardware translations. PA-RISC-based HP-UX systems allocate virtual address ranges for shared memory 
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all memory objects shared between processes. 
This implies the following: 

• Any single range of a file cannot be mapped multiply into different virtual address ranges. 

• After the initial MAP_SHARED mmap ( ) of a file range, all subsequent MAP_SHARED calls to 
mmap() to map the same range of a file must either specify MAP_VARIABLE in flags and 
inherit the virtual address range the system has chosen for this range, or specify MAP_PIXED 
with an addr that corresponds exactly to the address chosen by the system for the initial map- 
ping. Only after all mappings for a file range have been destroyed can that range be mapped to 
a different virtual address. 

• In most cases, two separate calls to mmap ( ) cannot map overlapping ranges in a file. The vir- 
tual address range reserved for a file range is determined at the time of the initial mapping of 
the file range into a process address space. The system allocates only the virtual address range 
necessary to represent the initial mapping. As long as the initial mapping exists, subsequent 
attempts to map a different file range that includes any portion of the initial range may fail with 
an ENOMEM error if an extended contiguous address range that preserves the mappings of the 
initial range cannot be allocated. 

• Separate calls to mmap ( ) to map contiguous ranges of a file do not necessarily return contigu- 
ous virtual address ranges. The system may allocate virtual addresses for each call to mmap ( ) 
on a first available basis. 

• The use of MAP_PIXED is strongly discouraged because it is not portable. Using MAP_PIXED 
is generally unsuccessful on this implementation, and when it is successful, it may prevent the 
system from optimally allocating virtual address space. 

The following combinations of protection modes are supported: 

PROT_NONE 

PROT_READ 

PROT_READ | PROT_EXECUTE 

PR0T_READ | PROTJWRITE 

PROT_READ | PROT_WRITE I PROT_EXECUTE 

If a MAP_PRIVATE mapping is created of a file for which a MAP_SHARED mapping exists, a separate 
copy of a page for the MAP_PRIVATE mapping is created at the time of the first access to the page through 
the private mapping. 

Series 300/400 

The following combinations of protection modes are supported: 

PROT_NONE 

PROTJREAD 

PROT_READ | PROT_EXECUTE 

PR0T_READ | PROT_WRITE 

PROT_READ | PROT_WRITE I PROT_EXECUTE 

In addition, for protection modes that do not explicitly have PROT_EXECUTE set, individual pages within 
the region can be promoted to include PROT_EXECUTE permissions simply by executing code located 
within the region. 

If a MAP_PRIVATE mapping is created of a file for which a MAP_SHARED mapping exists, a separate 
copy of a page for the MAP_PRIVATE mapping is created at the time of the first write reference to the page 
through the private mapping. 
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HP Clustered Environment 

In a clustered environment, modifications to a MAP_SHARED mapped file region on one cluster node may 
not be visible to other processes on other cluster nodes that have the same file mapped with the 
MAP_SHARED option. 

AUTHOR 

mmap ( ) was developed by HP, AT&T, and OSF. 

SEE ALSO 

fcntl(2), fork(2), ftruncate(2), lockf(2), madvise(2), mprotect(2), msem_init(2), msem_lock(2), 
msem_unlock(2), msync(2), munmap(2), sysconf(2), mman(5), stat(5). 

STANDARDS CONFORMANCE 

mmap ( ) : AES [Series 300/400/700 only] 



I 
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NAME 

mount - mount a file system 

SYNOPSIS 

#include < sys /mount .h> 

int mount (const char *spec, const char *dir, int rwf lag) ; 

DESCRIPTION 

mount ( ) requests that a removable file system contained on the block special device file identified by spec 
be mounted on the directory identified by dir. spec and dir are pointers to path names. 

Upon successful completion, references to the file dir refer to the root directory on the mounted file system. 

The low-order bit of rw flag is used to control write permission on the mounted file system. If it is 1, writing 
is forbidden; otherwise, writing is permitted according to individual file accessibility. 

mount ( ) can be invoked only by a user who has appropriate privileges. 

RETURN VALUE 

Upon successful completion a value of is returned. Otherwise, a value of -1 is returned and er mo is set 
to indicate the error. 

ERRORS 

mount ( ) fails if one or more of the following is true: 

[EPERM] The effective user ID is not a user who has appropriate privileges. 

[ENOENT] The named file does not exist (for example, path is null or a component of path does 

not exist). 

[ENOTDIR] A component of a path prefix is not a directory. 

[ENOTBLK] spec is not a block special device. 

[ENXIO] The device associated with spec does not exist. 

[ENOTDIR] dir is not a directory. 

[EFAULT] spec or dir points outside the allocated address space of the process. The reliable 

detection of this error is implementation dependent. 

[EBUSY] dir is currently mounted on, is someone's current working directory, or is otherwise 

busy. 

[EBUSY] The device associated with spec is currently mounted. 

[EBUSY] There are no more mount table entries. 

[ENOENT] spec or dir is null. 

[EACCES] A component of the path prefix denies search permission. 

[ENAMETOOLONG] 

The length of a specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ELOOP] Too many symbolic links were encountered in translating either path name. 

WARNINGS 

If mount ( ) is called from the program level (i.e. not called from mount(lNL)), the table of mounted devices 
contained in /etc/mnttab is not updated. Updating of /e tc/mnt tab is performed by mount( 1M) and 
syncer(]M). See corresponding manual entries for more information. 

In the HP Clustered environment, the spec and dir arguments should always be fully expanded pathnames. 

SEE ALSO 

mount(lM), syncer(lM), umount(2). 

STANDARDS CONFORMANCE 

mount ( ) : SVID2, XPG2 
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NAME 

mprotect - modify access protections of memory mapping 

SYNOPSIS 

ttinclude <sys/mman.h> 

int mprotect ( 

caddr_t addr, 
size_t len, 
int prot ) ; 

DESCRIPTION 

mprotect ( ) modifies the access protection of the memory mappings specified by the address range start- 
ing at addr and continuing for len bytes, rounded up to the next multiple of the page size, to be that 
specified by prot. If the address range does not correspond to one created by a successful call to rnrnap ( ) , 
mprotect ( ) returns an error, prot determines whether read, write, execute, or some combination of 
accesses are permitted to the data being mapped. Legitimate values for prot are the same as those permit- 
ted for mmap() (see mmap(2)). 

If the address range being modified corresponds to a mapped file that was mapped with MAP_SHARED, 
mprotect ( ) grants write access permission only if the file descriptor used to map the file was opened for 
writing. If the address range corresponds to a mapped file that was mapped with the MAP_PRIVATE or 
the MAP_ANONYMOUS flag, mprotect ( ) grants all requested access permissions. 

If mprotect ( ) fails under a condition other than that specified by EINVAL, the access protection of some 
of the pages in the range [addr, addr+len) (from, and including, addr to, but not including, addr+len) may 
have been changed. For example, suppose an error occurs on some page at an addr2; mprotect ( ) may 
have modified the protections of all whole pages in the range [addr,addr2]. 

RETURN VALUE 

mprotect ( ) returns upon success; otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

mprotect ( ) fails if any of the following conditions are encountered: 

[EACCES] prot specifies a protection that conflicts with the access permission set for the underly- 

ing file. 

[EINVAL] prot is invalid, or addr is not a multiple of the page size as returned by 

sysconf (_SC_PAGE_SIZE) . 

[ENOMEM] The range specified by [addr, addr+len) (from, and including, addr to, but not 

including, addr+len) is invalid for a process' address space, or the range specifies one 
or more unmapped pages. 

AUTHOR 

mprotect ( ) was developed by HP, AT&T, and OSF. 

SEE ALSO 

mmap(2), sysconf(2). 

STANDARDS CONFORMANCE 

mprotect ( ) : AES 
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NAME 

msem_init - initialize a semaphore in a mapped file or anonymous memory region 

SYNOPSIS 

ttinclude <sys/mman.h> 

msemaphore *msem_init (msemaphore *sem / int initial_value) ; 

DESCRIPTION 

msem_init ( ) allocates a new binary semaphore and initializes the state of the new semaphore. 

sem points to an msemaphore structure in which the state of the semaphore is to be stored. 

If initialjxdue is MSEM_LOCKED, the new semaphore is initialized in the locked state. If initial _value is 
MSEM_UNLOCKED, the new semaphore is initialized in the unlocked state. 

The msemaphore structure must be located within a mapped file or anonymous memory region created 
by a successful call to mmap ( ) and have both read and write access. 

If a semaphore is created in a mapped file region, any reference by a process that has mapped the same file, 
using a (struct msemaphore *) pointer that resolves to the same file offset is interpreted as a refer- 
ence to the same semaphore. If a semaphore is created in an anonymous memory region, any reference by a 
process sharing the same region by use of a (struct msemaphore *) pointer that resolves to the 
same offset from the start of the region is interpreted as a reference to the same semaphore. 

Any previous semaphore state stored in the msemaphore structure is be ignored and overwritten. 

IMPLEMENTATION NOTES 

In order to ensure that an msemaphore structure is entirely contained in a single memory page, sem 
must be at an address that is an exact multiple of sizeof (structmsemaphore). The size of the 
msemaphore structure is guaranteed to prevent semaphores that cross page boundaries given the above 
restriction. 

For a memory mapped file region, the system deallocates memory that corresponds to a range of the file 
that has been truncated with f truncate ( ) or truncate ( ) . If a semaphore is located in memory so 
deallocated, the effect is equivalent to an msem_remove ( ) on the semaphore. 

RETURN VALUE 

msem_lnit ( ) returns the address of the initialized msemaphore structure; otherwise, it returns NULL 
and sets errno to indicate the error. NOTE: This error return value may change to -1 in a future HP-UX 
release. For portability, applications should check for a zero or negative value for error returns. 

ERRORS 

msem_init ( ) fails if any of the following conditions are encountered: 

[EINVAL] sem points to an msemaphore structure that is not located in a mapped region 

created by mmap ( ) and with read and write access, or initial _value is not valid. 

[ENOMEM] A new semaphore could not be created. 

[EFAULT] sem is an invalid pointer. 

AUTHOR 

msem_init ( ) was developed by HP and OSF. 

SEE ALSO 

mmap(2), msem_lock(2), msem_remove(2), msem_unlock(2), mman(5). 

STANDARDS CONFORMANCE 

msem_init():AES 
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NAME 

msem_lock - lock a semaphore 

SYNOPSIS 

#include <sys/mman.h> 

int msem_lock(msemaphore *sem, int condition); 

DESCRIPTION 

msem_lock ( ) attempts to lock a binary semaphore. 

sem points to an msemaphore structure which specifies the semaphore to be locked. 

If the semaphore is not currently locked, it becomes locked and the function returns successfully. 

If the semaphore is currently locked, and condition is MSEM_IF_NOWAIT, then the function returns with 
an error. If the semaphore is currently locked and condition is zero, the function does not return until 
either the calling process is able to successfully lock the semaphore, or an error condition occurs. 

All calls to msem_lock() and msem_unlock ( ) by multiple processes sharing a common msema- 
phore structure behave as if the calls were serialized. 

If the msemaphore structure contains any value not resulting from a call to msem_init ( ) followed by 
a (possibly empty) sequence of calls to msem_lock( ) and msem_unlock( ), the results are undefined. 
The address of an msemaphore uniquely identifies the semaphore. If the msemaphore structure con- 
tains any value copied from an msemaphore structure at a different address, the result is undefined. 

IMPLEMENTATION NOTES 

If blocked on a locked semaphore, msem_lock ( ) suspends the calling process at a priority such that the 
process can be interrupted by a signal. 

The system attempts to ignore or recover from invalid values written to the msemaphore structure, but 
this is not guaranteed for all cases. 

msem_lock ( ) successfully acquires a semaphore that is locked by a process that has exited. 

RETURN VALUE 

Upon success, msem_lock ( ) returns zero; otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

msem_lock ( ) fails if any of the following conditions are encountered: 

[EAGAIN] MSEM_IP_NOWAIT was specified and the semaphore was already locked. 

[EINVAL] sem points to an msemaphore structure that has been removed, or condition is 

invalid. 

[EINTR] msem_lock ( ) was interrupted by a signal that was caught. 

[EDEADLK] The semaphore is currently locked, condition is zero, and waiting to lock the sema- 
phore would create a deadlock. 

[EFAULT] sem is not a properly aligned address or is otherwise an invalid pointer. 

AUTHOR 

msem_lock ( ) was developed by HP and OSF. 

SEE ALSO 

msem_init(2), msem_remove(2), msem_unlock(2), mman(5). 

STANDARDS CONFORMANCE 

msem_lock ( ) : AES 
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NAME 

msem_remove - remove a semaphore in mapped file or anonymous region 

SYNOPSIS 

ttinclude <sys/xnman.h> 

int *msem_remove (msemaphore *sem) ; 



msem_remove ( ) removes a binary semaphore. 

sem points to an msemaphore structure that specifies the semaphore to be removed. Any subsequent use 
of the msemaphore structure before it is again initialized by calling msem_init ( ) produces undefined 
results. 
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phore to return with an error. 

If the msemaphore structure contains any value not resulting from a call to msem_init ( ) followed by 
a (possibly empty) sequence of calls to msem_lock ( ) and msem_unlock ( ) , the results are undefined. 
The address of an msemaphore uniquely identifies the semaphore. If the msemaphore structure con- 
tains any value copied from a msemaphore structure at a different address, the result is undefined. 

RETURN VALUE 

Upon success, msem_remove ( ) returns zero; otherwise, it returns -1 and sets errno to indicate the 
error. 

ERRORS 

msem_remove ( ) fails if any of the following conditions are encountered: 

[EINVAL] sem points to an msemaphore structure that has been removed. 

DEFAULT] sem is an invalid pointer. 

AUTHOR 

msem_remove ( ) was developed by HP and OSF. 

SEE ALSO 

msem_init(2), msem_lock(2), msem_remove(2), mman(5). 

STANDARDS CONFORMANCE 

msein_remove ( ) : AES 
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NAME 

msem_unlock - unlock a semaphore 

SYNOPSIS 

#include <sys/mman.h> 

int msem_unlock (msemaphore *sem, int condition); 

DESCRIPTION 

msem_unlock ( ) unlocks a binary semaphore. 

sem points to an n>.ssn>.sph.ors structure that specifies the semaphore to be unlocked. 

If the condition argument is zero, the semaphore will be unlocked, whether or not any other processes are 
currently attempting to lock it. If the condition argument is MSEM_IF_WAITERS, and some other process 
is waiting to lock the semaphore or the implementation cannot reliably determine whether some process is 
waiting to lock the semaphore, the semaphore is unlocked by the calling process. If the condition argument 
is MSEM_IP_WAITERS, and no process is waiting to lock the semaphore, the semaphore is not unlocked 
and an error is returned. 

All calls to msem_lock() and msem_unlock() by multiple processes sharing a common msema- 
phore structure behave as if the calls were serialized. 

If the msemaphore structure contains any value not resulting from a call to msem_init ( ) followed by 
a (possibly empty) sequence of calls to msem_lock ( ) and msem_unlock ( ) , the results are undefined. 
The address of an msemaphore uniquely identifies the semaphore. If the msemaphore structure con- 
tains any value copied from a msemaphore structure at a different address, the result is undefined. 

IMPLEMENTATION NOTES 

The system attempts to ignore or recover from invalid values placed in the msemaphore structure, but 
this is not guaranteed for all cases. 

RETURN VALUE 

Upon success, msem_unlock() returns zero; otherwise, it returns -1 and sets errno to indicate the 
error. 

ERRORS 

msem_unlock ( ) fails if any of the following conditions are encountered: 

[EAGAIN] MSEM_IP_NOWAIT was specified and there were no waiters. 

[EINVAL] sem points to an msemaphore structure that has been removed, or condition is 

invalid. 

[EFAULT] sem is an invalid pointer. 

AUTHOR 

msem_unlock ( ) was developed by HP and OSF. 

SEE ALSO 

msem_init(2), msem_lock(2), msem_remove(2), mman(5). 

STANDARDS CONFORMANCE 

msem_unlock ( ) : AES 
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NAME 

msgctl - message control operations 

SYNOPSIS 

# include <sys/msg.h> 

int msgctl (int msqid, int cmd, struct msqid_ds *buf ) ; 

DESCRIPTION 

msgctl ( ) provides a variety of message control operations as specified by cmd. The following cmds are 
available: 

IPC_STAT Place the current value of each member of the data structure associated with msqid 
into the structure pointed to by buf. The contents of this structure are defined in 

alnaerm)(Qi\ 

IPC_SET Set the value of the following members of the data structure associated with msqid to 

the corresponding value found in the structure pointed to by buf: 
msg_perm.uid 
msg_perm.gid 

msg_perm.mode /* only low 9 bits */ 
msg_qbytes 

This cmd can only be executed by a process that has an effective user ID equal to either that of super-user 
or to the value of either msg_perm.uld or msg_perm.cuid in the data structure associated with 
msqid. Only super-user can raise the value of msg_qbytes. 

IPCJRMID 

Remove the message queue identifier specified by msqid from the system and destroy the message queue 
and data structure associated with it. This cmd can only be executed by a process that has an effective 
user ID equal to either that of super-user or to the value of either msg_perm.uid or 
msg perm.culd in the data structure associated with msqid. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

msgctl ( ) fails if one or more of the following is true: 

[EINVAL] msqid is not a valid message queue identifier. 

[EINVAL] cmd is not a valid command. 

[EACCES] cmd is equal to IPC_STAT and Read operation permission is denied to the calling process 

(see message operation permissions in glossary (9)). 

[EPERM] cmd is equal to IPC_RMID or IPCJSET and the effective user ID of the calling process is 

not equal to that of a user who has appropriate privileges and it is not equal to the value of 
either msg_perm.uid or msg_perm.cuid in the data structure associated with 
msqid. 

[EPERM] cmd is equal to IPC_SET, an attempt is being made to increase to the value of 

msg_qbytes, and the effective user ID of the calling process is not equal to that of super- 
user. 

[EFAULT] buf points to an illegal address. Reliable detection of this error is implementation depen- 

dent. 

SEE ALSO 

ipcrm(l), ipcs(l), msgget(2), msgop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

msgctl () : SVID2, XPG2, XPG3, XPG4 
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NAME 

msgget - get message queue 

SYNOPSIS 

# include <sys/msg.h> 

int msgget (key_t key, int msgflg); 

DESCRIPTION 

msgget ( ) returns the message queue identifier associated with key . 

A message queue identifier and associated message queue and data structure are created for key if one of 
the following is true: 

key is equal to IPC_PRIVATE. This call creates a new identifier, subject to available resources. The 
identifier will never be returned by another call to msgget ( ) until it has been released by a call to 
msgctl ( ) . The identifier should be used among the calling process and its descendents; however, it 
is not a requirement. The resource can be accessed by any process having the proper permissions. 

key does not already have a message queue identifier associated with it, and {msgflg & IPC_CREAT) 
is "true". 

Upon creation, the data structure associated with the new message queue identifier is initialized as follows: 

msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid are set equal to the 
effective user ID and effective group ID, respectively, of the calling process. 

The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 bits of msgflg. 

msg_qnum, msg_lspid, msg_lrpid, msg_st ime, and msg_rt ime are set equal to 0. 

msg_ct ime is set equal to the current time. 

msg_qbytes is set equal to the system limit. 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a message queue identifier, is returned. Other- 
wise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

msgget ( ) fails if one or more of the following is true: 

[EACCES] A message queue identifier exists for key, but operation permission as specified by the low- 

order 9 bits of msgflg would not be granted. 

[ENOENT] A message queue identifier does not exist for key and {msgflg & IPC_CREAT) is "false". 

[ENOSPC] A message queue identifier is to be created but the system-imposed limit on the maximum 

number of allowed message queue identifiers system wide would be exceeded. 

[EEXIST] A message queue identifier exists for key but {{msgflg & IPC_CREAT) && {msgflg & 

IPC_EXCL))is < true". 

SEE ALSO 

ipcrm(l), ipcs(l), msgctl(2), msgop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

msgget ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

msgsnd, msgrcv - message operations 

SYNOPSIS 

# include <sys/msg.h> 

int msgsnd ( 

int msqid, 

const void *msgp, 

size_t msgsz, 

int msgflg 
); 

int msgrcv ( 

int msqid, 

void *msgp / 

size_t msgsz, 

long msgtyp, 

int msgflg 
); 

DESCRIPTION 

msgsnd ( ) is used to send a message to the queue associated with the message queue identifier specified 
by msqid. 

msgp points to a user-defined buffer that must contain first a field of type long that specifies the type of 
the message, followed by a data portion that will hold the data bytes of the message. The structure below is 
an example of what this user-defined buffer might look like: 

long mtype; /* message type */ 
char mtext[]; /* message text */ 

mtype is a positive integer that can be used by the receiving process for message selection (see 
msgrcv () below), mtext is any text of length msgsz bytes, msgsz can range from to a system- 
imposed maximum. 

msgflg specifies the action to be taken if one or more of the following is true: 

The number of bytes already on the queue is equal to msg_qbytes (see message queue identifier in 
glossary^)). 

The total number of messages on all queues system-wide is equal to the system-imposed limit. 

These actions are as follows: 

If (msgflg & IPC_NOWAIT) is 'true", the message is not sent and the calling process returns 
immediately. 

If (msgflg & IPC_NOWAIT) is "false", the calling process suspends execution until one of the follow- 
ing occurs: 

The condition responsible for the suspension no longer exists, in which case the message is 
sent. 

msqid is removed from the system (see msgctl(2)). When this occurs, errno is set equal to 
EIDRM, and a value of -1 is returned. 

The calling process receives a signal to be caught. In this case the message is not sent and the 
calling process resumes execution in the manner prescribed in signal(5). 

Upon successful completion, the following actions are taken with respect to the data structure associated 
•with, msqid: 

msg_qnum is incremented by 1. 

msg_lspid is set equal to the process ID of the calling process. 

msg_st ime is set equal to the current time. 
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msgrcv ( ) reads a message from the queue associated with the message queue identifier specified by 
msqid and places it in the structure pointed to by msgp. This structure is composed of the following 
members: 

long mtype; /* message type */ 
char mtext[]; /* message text */ 

mtype is the received message's type as specified by the sending process, mt ext is the text of the mes- 
sage, msgsz specifies the size in bytes of mtext. The received message is truncated to msgsz bytes if it is 
larger than msgsz and (msgflg &B MSG_NOERROR) is "true". The truncated part of the message is lost 
and no indication of the truncation is given to the calling process. 

msgtyp specifies the type of message requested as follows: 

msgtyp = First message on the queue is received. 

msgtyp > First message of type msgtyp is received. 

msgtyp < First message of the lowest type that is less than or equal to the absolute value of 
msgtyp is received. 

msgflg specifies the action to be taken if a message of the desired type is not on the queue. These are as fol- 
lows: 

imsgflg & IPC_NOWAIT) is 'true": 

Calling process returns immediately with a return value of -1 and errno set to ENOMSG. 

(msgflg & IPC_NOWAIT) is "false": 

Calling process suspends execution until one of the following occurs: 

• A message of the desired type is placed on the queue. 

• msqid is removed from the system. When this occurs, errno is set equal to EIDRM, 
and a value of -1 is returned. 

• The calling process receives a signal that is to be caught. In this case, a message is not 
received and the calling process resumes execution in the manner prescribed in sig- 
nal(5)). 

Upon successful completion, the following actions are taken with respect to the data structure associated 
with msqid. 

msg_qnumis decremented by 1. 

msg_lrpid is set equal to the process ID of the calling process. 

msg_rtime is set equal to the current time. 

RETURN VALUES 

Upon successful completion, the return value is as follows: 

msgsnd ( ) returns a value of 0. 

msgrcv ( ) returns a value equal to the number of bytes actually placed into mtext. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

msgsnd ( ) fails and no message is sent if one or more of the following is true: 

[EINVAL] msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process. 

[EINVAL] mtype is less than 1. 

[EAGAIN] The message cannot be sent for one of the reasons cited above and (msgflg & 

IPC_NOWAIT) is "true". 

[EINVAL] msgsz is less than zero or greater than the system-imposed limit. 

[EFAULT] msgp points to an illegal address. The reliable detection of this error is implementa- 

tion dependent. 

\ 
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[EIDRM] The message queue identifier msqid has been removed from the system. 

[EINTR] msgsnd() was interrupted by a signal. 

msgrcv ( ) fails and no message is received if one or more of the following is true: 

[EINVAL] msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process. 

[EINVAL] msgsz is less than 0. 

[E2BIG] mtext is greater than msgsz and (msgflg & MSG_NOERROR) is "false". 

[ENOMSG] The queue does not contain a message of the desired type and (msgflg &. 

IPC_NOWAIT) is "true". 

[EFAULT] msgp points to an illegal address. The reliable detection of this error is implementa- 

tion dependent. 

[EIDRM] The message queue identifier msqid has been removed from the system. 

[EINTR] The function msgrcv ( ) was interrupted by a signal. 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can 
affect the behavior described on this page. 

SEE ALSO 

ipcs(l), msgctl(2), msgget(2), signal(5), stdipc(3C). 

STANDARDS CONFORMANCE 

msgrcv ( ) : SVID2, XPG2, XPG3, XPG4 

msgsnd ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

msync - synchronize a mapped file 

SYNOPSIS 

#include <sys/mman.h> 

int msync ( caddr_t addr,size_t len, int flags); 

DESCRIPTION 

msync controls the caching operations of a mapped file region, msync ( ) writes all modified pages in the 
region to the file's underlying storage device, and ensures the visibility of modifications made to the region 
with respect to file system operations. 

addr and len specify the region to be synchronized. If these are not the address and length of a region 
created by a previous successful call to mmap ( ) , msync ( ) returns an error. The behavior of msync ( ) 
upon a region created with the MAP_ANONYMOUS or MAP_PRIVATE flags is undefined. 

flags is constructed from the bitwise inclusive OR of one or more of the following flags denned in 
<sys /mman . h>: 

MS_SYNC Perform synchronous writes 

MS_ASYNC Perform asynchronous writes 

MS_INVALIDATE Invalidate cached pages 

If MS_SYNC is specified, msync ( ) does not return until the system completes all I/O operations. If 
MS_ASYNC is specified, msync ( ) returns after the system schedules all I/O operations. Either 
MS_SYNC or MS_AS YNC can be set in flags, but not both. 

If MS_INVALIDATE is specified, msync ( ) invalidates all cached copies of the pages. Subsequent refer- 
ences to the mapped data is obtained from the file's permanent storage locations. If either MS_SYNC or 
MS_ASYNC is also specified, a page is invalidated after it has been written to the file. 

After a successful call to msync ( ) with MS_SYNC specified, all previous modifications to the mapped 
region are visible to processes using read ( ) . Previous modifications to the file using write ( ) may be 
lost. 

After a successful call to msync ( ) with only MS_INVALIDATE specified, all previous modifications to 
the file using write () are visible to the mapped region. Previous direct modifications to the mapped 
region may be lost. 

RETURN VALUE 

msync ( ) returns upon success; otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

msync ( ) fails if any of the following conditions are encountered.: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOMEM] The range specified by [addr, addr+len) (from, and including, addr to, but not 

including, addr+len) is invalid for a process' address space, or the range specifies one 
or more unmapped pages. 

[EINVAL] addr is not a multiple of the page size as returned by 

sysconf (_SC_PAGE_SIZE) . 

[EINVAL] The address range specified by addr and len was not created by a successful call to 

mmap ( ) . 

AUTHOR 

msync ( ) was developed by HP, AT&T, and OSF. 

SEE ALSO 

mmap(2), sysconf(2). 

STANDARDS CONFORMANCE 

msync ( ) : AES 
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NAME 

munmap - unmap a mapped region 

SYNOPSIS 

#include <sys/mman.h> 

int munmap (caddr_t addr, size__t len) ; 

DESCRIPTION 

munmap ( ) unmaps a mapped file or anonymous memory region. 

munmap ( ) unmaps pages in the address range starting at addr and continuing for len bytes rounded up to 
the next multiple of the page size. Further references to these pages result in the delivery of a SIGSE6V 
signal to the process. 

If the address range specified by addr and len was not created by a successful call to ramap ( ) , munmap ( ) 
returns an error. 

If the specified address range was created by multiple calls to mmap ( ) , munmap ( ) succeeds in unmap- 
ping all of the specified regions, provided they form a contiguous address range. 

If the region was created with the MAP_PRIVATE option, any modifications made to the region are dis- 
carded. 

RETURN VALUE 

munmap ( ) returns upon success; otherwise, it returns -1 and sets errno to indicate the error. 

ERRORS 

munmap ( ) fails if any of the following conditions are encountered: 

[EINVAL] addr is not a multiple of the page size as returned by 

sysconf (_SC_PAGE_SIZE) . 

[EINVAL] The address range specified by addr and len was not created by a successful call to 

mmap ( ) . 

AUTHOR 

munmap ( ) was developed by HP, AT&T, and OSF. 

SEE ALSO 

mmap(2), sysconf(2). 

STANDARDS CONFORMANCE 

munmap ( ) : AES 
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NAME 

nfssvc, async_daemon - NFS daemons 

SYNOPSIS 

int nfssvc (int sock); 

void async_daemon( ) ; 

DESCRIPTION 

nfssvc ( ) starts an NFS daemon listening on socket sock. The socket must be AFJNET and SOCK.DGRAM 
(protocol UDP/IP). The system call returns only if the process is killed. 

asyncjdaemon implements the NFS daemon that handles asynchronous I/O for an NFS client. The system 
call never returns. 

ERRORS 

nfssvc ( ) fails if any of the following conditions is encountered, and sets errno accordingly: 

[EBADF] sock is not a valid socket descriptor. 

[EINVAL] sock refers to a socket that is not an AFJNET and SOCKJDGRAM socket. 

async_daemon fails if the following condition is encountered, and sets errno accordingly: 
[ENOMEM] There are not enough resources to create the process. 

WARNINGS 

This call should be used only by HP-supplied commands and is not recommended for use by non-HP- 
supplied programs. 

These two system calls allow kernel processes to have user context. 

AUTHOR 

nfssvc ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

mountdUM), nfsd(lM). 
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NAME 

nice - change priority of a process 

SYNOPSIS 

#include <unistd.h> 

int nice(int prior ity_change) ; 

DESCRIPTION 

nice ( ) adds the value of priority _change to the nice value of the calling process. A process's nice value 
is a positive number for which a more positive value results in lower CPU priority. 

A maximum nice value of 39 and a minimum nice value of are imposed by the system. Requests for 
values above or below these limits result in the nice value being set to the corresponding limit. 

RETURN VALUE 

Upon successful completion, nice ( ) returns the new nice value minus 20. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 

Note that nice ( ) assumes a user process priority value of 20. If a user having appropriate privileges has 
changed the user process priority value to something less than 20, certain values for priority _change can 
cause nice ( ) to return -1, which is indistinguishable from an error return. 

ERRORS 

[EPERM] nice ( ) fails and does not change the nice value if priority _change is negative or greater 

than 40, and the effective user ID of the calling process is not a user having appropriate 
privileges. 

SEE ALSO 

nice(l), renice(l), exec(2). 

STANDARDS CONFORMANCE 

nice () : AES, SVTD2, XPG2, XPG3, XPG4 
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NAME 

open - open file for reading or writing 

SYNOPSIS 

ttinclude <fcntl.h> 

int open( 

const char *path, 

int of lag, . . . 

/* mode_t mode */ 
); 

DESCRIPTION 

open ( ) opens a file descriptor for the named file and sets the file status flags according to the value of 
oflag. path points to a path name naming a file, and must not exceed PATH_MAX bytes in length, oflag 
values are constructed by OR-ing flags from the fist below. 

Exactly one of the flags 0_RDONLY, 0_WRONLY, or 0_RDWR must be used in composing the value of oflag. 
If none or more than one is used, the behavior is undefined. Several other flags listed below can be changed 
by using f cnt 1 ( ) while the file is open. See fcntl{2) andfcntl(5) for details. 

0_RDONLY Open for reading only. 

OJWRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

0_NDELAY This flag might affect subsequent reads and writes. See read(2) and write(2). 

When opening a FIFO with 0_RDONLYor 0_WRONLY set: 

If 0_NDELAY is set: 

An open ( ) for reading-only returns without delay. An open ( ) for 
writing-only returns an error if no process currently has the file open for 
reading. 

If 0_NDELAY is clear: 

An open ( ) for reading-only does not return until a process opens the file for writing. An 
open ( ) for writing-only does not return until a process opens the file for reading. 

When opening a file associated with a communication line: 

If 0_NDELAY is set: 

The open ( ) returns without waiting for carrier. 

If 0_NDELAY is clear: 

The open ( ) does not return until carrier is present. 

0_NONBLOCK 
Same effect as 0_NDELAY for open(2), but slightly different effect in read(2) and write(2). Only one of 
0_NONBLOCK and 0_NDELAY can be specified. 

0_APPEND 
If set, the file offset is set to the end of the file prior to each write. 

0_CREAT 
If the file exists, this flag has no effect, except as noted under 0_EXCL below. Otherwise, the owner ID 
of the file is set to the effective user ID of the process, the group ID of the file is set to the effective group 
ID of the process if the set-group-ID bit of the parent directory is not set, or to the group ID of the parent 
directory if the set-group-ID bit of the parent directory is set. The file access permission bits of the file 
mode are set to the value of mode modified as follows (see creat(2)): 

• For each bit set in the file mode creation mask of the process, the corresponding bit in the new 
file's mode is cleared (see umask(2)). 

• The "save text image after execution" bit of the mode is cleared. See chmod(2). 

• On systems with access control lists, three base ACL entries are created corresponding to the file 
access permissions (see acZ(5)). 
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0_TRUNC 
If the file exists, its length is truncated to and the mode and owner are unchanged. 

0_EXCL 
If CMEXCL and 0_CREAT are set, open ( ) fails if the file exists. 

0_NOCTTY 
If set, and path identifies a terminal device, open ( ) does not cause the terminal to become the control- 
ling terminal for the process. 

0_SYNC 
If a file is opened with 0_SYNC or if that flag is set with the P_SETPL option of f cnt 1 ( ) , file system 
writes for the file are done through the cache to the disk as soon as possible, and the process blocks until 
the data is written to the buffer cache. This flag is ignored by all I/O calls except write ( ) , and is 
ignored for files other than ordinary files and block special devices on those systems that permit I/O to 
block special devices. 

The name 0_SYNCIO is a synonym for 0_SYNC, and is defined for backward compatibility in 
<fcntl.h>. 

The file pointer used to mark the current position within the file is set to the beginning of the file. 

The new file descriptor is set to remain open across exec system calls; seefcntl(2). 

EXAMPLES 

The following call to open ( ) opens file inputfile for reading only and returns a file descriptor for inputfile. 
For an example of reading from file inputfile, see the read(2) manual entry. 

int myfd; 

myfd = open ("inputfile", 0_RDONLY); 

The following call to open ( ) opens file outputfile for writing and returns a file descriptor for outputfile. 
For an example of preallocating disk space for outputfile, see the prealloc(2) manual entry. For an exam- 
ple of writing to outputfile, see the write(2) manual entry. 

int outfd; outfd = open ("outputfile", OJWRONLY) ; 

RETURN VALUE 

Upon successful completion, the file descriptor is returned. Otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

open ( ) fails and the file is not opened if any of the following conditions are encountered: 

[EACCES] oflag permission is denied for the named file. 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] The file does not exist and the directory in which the file is to be created does not per- 

mit writing. 

[EAGAIN] One or more segments of a pre-existing file have been locked with lockf or fcntl by 

some other process, and 0_TRUNC is set. 

[EAGAIN] The file exists, enforcement mode file/record locking is set, and there are outstanding 

record locks on the file (see chmod(2)). 

[EDQUOT] User's disk quota block or inode limit has been reached for this file system. 

[EEXIST] 0_CREAT and 0_EXCL are set and the named file exists. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the open ( ) system call, and the system call was not 

restarted (see signal(5) and sigvector(2)). 

[EINVAL] oflag specifies both 0_WRONLY and 0_RDWR. 

[EINVAL] oflag specifies both 0_NONBLOCK and 0_NDELAY. 
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[EISDIR] The named file is a directory and oflag is write or read/write. 

[ELOOP] Too many symbolic links are encountered in translating the path name. 

[EMFILE] The maximum number of file descriptors allowed are currently open. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENFILE] The system file table is rail. 

[ENOENT] The named file does not exist (for example, path is null or a component of path does 

not exist, or the file itself does not exist and 0_CREAT is not set). 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] 0_NDELAY is set, the named file is a FIFO, 0_WRONLY is set, and no process has the 

file open for reading. 

[ENODEV] The named file is a character special or block special file, and the device associated 

with this special file either does not exist, or the driver for this device has not been 
configured into the kernel. 

[EROFS] The named file resides on a read-only file system and oflag is write or read/write. 

[ETXTBSY] The file is open for execution and oflag is write or read/write. Normal executable files 

are only open for a short time when they start execution. Other executable file types 
can be kept open for a long time, or indefinitely under some circumstances. 

DEPENDENCIES 

HP Clustered Environment: 

Attempting to open a device file with a st_rcnode value that does not match the cnode ID of the 
machine on which the calling process is running (or 0) fails with an EOPNOTSUPP error. 

WARNINGS 

Access Control Lists 

Access control list descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control fists in the HP-UX BLS environment. 

AUTHOR 

open ( ) was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), lockf(2), lseek(2), read(2), select(2), setacl(2), umask(2), write(2), 
acl(5), fcntl(5), signal(5). 

STANDARDS CONFORMANCE 

open ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
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NAME 

pathconf(), fpathconfQ - get configurable pathname variables 

SYNOPSIS 

ttinclude <unistd.h> 

long pathconf (const char *path, int name); 
long fpathconf (lnt fildes, lnt name); 

DESCRIPTION 

pathconf ( ) and fpathconf ( ) provide a method for applications to determine the value of a 
configurable limit or option associated with a file or directory (see limits(5) and <unis td . h>). 

For pathconf ( ) , the path argument points to the path name of a file or directory. 

For fpathconf ( ) , the fildes argument is an open file descriptor. 

For both functions, the name argument represents the variable to be queried regarding the file or directory 
to which the other argument refers. 

The following table lists the configuration variables available from pathconf ( ) and fpathconf ( ) , 
and lists for each variable the associated value of the name argument: 



Variable 


Value of name 


Notes 


LINK_MAX 


_PC_LINK_MAX 


1 


MAX_CANON 


_PC_MAX_CANON 


2 


MAX_INPUT 


_PC_MAX_INPUT 


2 


NAME_MAX 


_PC_NAME_MAX 


3,4 


PATHJMAX 


_PC_PATH_MAX 


4,5 


PIPE_BUF 


_PC_PIPE_BUF 


6 


_POSIX_CHOWN_RESTRICTED 


_PC_CHOWN_RESTRICTED 


7,8 


_POSIX_NO_TRUNC 


_PC_NO_TRUNC 


3,4 


_POSIX_VDISABLE 


_PC_V_DISABLE 


2 



The variables in the table are defined as constants in < limits .h> or <unistd.h> if they do not vary 
from one pathname to another. The associated values of the name argument are defined in <unistd .h>. 

RETURN VALUE 

The following notes further qualify the table above. 

1. If path or fildes refers to a directory, the value returned applies to the directory itself. 

2. If the variable is constant, the value returned is identical to the variable's definition in 
<limits.h> or <unistd.h> regardless of the type of fildes or path. The behavior is 
undefined if path or fildes does not refer to a terminal file. 

3. If path or fildes refers to a directory, the value returned applies to the filenames within the direc- 
tory. 

4. If path or fildes does not refer to a directory, pathconf ( ) or fpathconf ( ) returns -1 and 
sets errnotoEINVAL. 

5. If path or fildes refers to a directory, the value returned is the maximum length of a relative path 
name when the specified directory is the working directory. 

6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the value returned applies to the pipe or 
l FIFO itself. If path or fildes refers to a directory, the value returned applies to any FIFOs that 

exist or can be created within the directory. If PIPE_BUP is a constant, the value returned is 
identical to the definition of PIPE_BUF in <limits.h> regardless of the type of fildes or 
path . The behavior is undefined for a file other than a directory, FIFO, or pipe. 

7. If path or fildes refers to a directory, the value returned applies to files of any type, other than 
directories, that exist or can be created within the directory. 

8. _POSIX_CHOWN_RESTRICTED is denned if the privilege group PRIV_GLOBAL has been 
granted the CHOWN privilege (see getprivgrp{2) and chown(2)). In all other cases, 
_POSIX_CHOWN_RESTRICTED is undefined and pathconf or fpathconf returns -1 without 
changing errno. To determine Mchown can be performed on a file, it is simplest to attempt the 
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chown ( ) operation and check the return value for failure or success. 

If the variable corresponding to name is not defined for path or fildes, the pathconf and fpathconf functions 
succeed and return a value of - 1, without changing the value of er mo. 

Upon any other successful completion, these functions return the value of the named variable with respect 
to the specified file or directory, as described above. 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

pathconf and fpathconf fail if any of the following conditions are encountered: 

[EACCES] A component of the path prefix denies search permission. 

[EBADF] The fildes argument is not a valid open file descriptor. 

[EFAULT] path points outside the allocated address space of the process. 

[EINVAL] The value of name is not valid or the implementation does not support an associ- 

ation of the variable name with the specified file. 

[ELOOP] Too many symbolic finks were encountered in translating path. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[ENOENT] The file named by path does not exist (for example, path is null or a component 

of path does not exist). 

[ENOTDIR] A component of the path prefix is not a directory. 

EXAMPLES 

The following example sets val to the value of MAX_CANON for the device file being used as the standard 
input. If the standard input is a terminal, this value is the maximum number of input characters that can 
be entered on a single input line before typing the newline character: 

if (isatty(O)) 

val = fpathconf (0, _PC_MAX_CANON) ; 

The following code segment shows two calls to pathconf, one to determine whether a file name longer than 
NAME_MAX bytes will be truncated to NAME_MAX bytes in the /tmp directory, and if so, another call to 
determine the actual value of NAME_MAX so that an error can be printed if a user-supplied file name 
stored in filebufwiH be truncated in this directory: 

extern int errno; 
char *filebuf; 

errno =0; /* reset errno */ 

if ( pathconf ("/tmp" _PC_NO_TRUNC) == -1 ) { 

/* _POSIX_NO_TRUNC is not in effect for this directory */ 
if (strlen(filebuf) > pathconf ("/tmp", PC_NAME_MAX) ) { 

fprintf (stderr, "Filename %s too long.\n", filebuf) 
/* take error action */ 
} 
else 

if (errno) { 

perror ( "pathconf" ) ; 
/* take error action */ 
} 
} 
/* otherwise, _POSIX_NO_TRUNC is in effect for this directory */ 
if ((fd = open(filebuf, 0_CREAT, mode)) < 0) 
perror (f ilebuf ) ; 

DEPENDENCIES 

NFS 

The following error can occur: 
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[EOPNOTSUPP] path or fildes refers to a file for which a value for name cannot be determined. In par- 
ticular, _PC_LINK_MAX, _PC_NAME_MAX, _PC_PATH_MAX, _PC_NO_TRUNC, 
and _PC_CHOWN_RESTRICTED, cannot be determined for an NFS file. 

AUTHOR 

pathconf ( ) and f pathconf ( ) were developed by HP. 

SEE ALSO 

errno(2), chown(2), limits(5), unistd(5), termio(7). 

STANDARDS CONFORMANCE 

pathconf ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, POSIX.2 

f pathconf ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, POSIX.2 
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NAME 

pause - suspend process until signal 

SYNOPSIS 

# include <unistd.h> 

int pause (void) ; 

DESCRIPTION 

pause () suspends the calling process until it receives a signal. The signal must be one that is not 
currently set to be ignored or blocked (masked) by the calling process. 

If the signal causes termination of the calling process, pause ( ) does not return. 

If the signal is caught by the calling process and control is returned from the signal-catching function (see 
signal(.5)\ the calling process resumes execution from the point of suspension; with a return value of -1 
from pause ( ) and errno set to EINTR. 

WARNING 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvec- 
tor ( ) can affect the behavior described on this page. 

SEE ALSO 

alarm(2), kill(2), sigvector(2), wait(2), signal(5). 

STANDARDS CONFORMANCE 

pause ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

pipe - create an interprocess channel 

SYNOPSIS 

int pipe(int fildes[2]); 

DESCRIPTION 

pipe() creates an I/O mechanism called a pipe and returns two file descriptors, fildes[0] and fildes[l]. 
fildes[0] is opened for reading and fildes[l] is opened for writing. 

A read-only file descriptor fildes[0] accesses the data written to fildes[l] on a first-in-first-out (FIFO) basis. 
For details of the I/O behavior of pipes see read(2) and write(2). 

EXAMPLES 

The following example uses pipe ( ) to implement the command string Is | sort: 

ttinclude <sys/types.h> 
pid_t pid; 
int pipefd[2] ; 

/* Assumes file descriptor and 1 are open */ 
pipe (pipefd) ; 

if ((pid = forkO) == (pid_t)0) { 

close (1); /* close stdout */ 

dup (pipefd [1]); 

close (pipefd[0]); 

execlp ("Is", "Is", (char *)0); 
} 
else if (pid > (pid_t)0) { 

close (0); /* close stdin */ 

dup (pipefd [0]); 

close (pipefd [1 ] ) ; 

execlp ("sort", "sort", (char *)0); 
} 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

pipe ( ) fails if one or more of the following is true: 

[EMFILE] NFILE - 1 or more file descriptors are currently open. 

[ENFILE] The system file table is full. 

[ENOSPC] The file system lacks sufficient space to create the pipe. 

SEE ALSO 

sh(l), read(2), write(2), popen(3S). 

STANDARDS CONFORMANCE 

pipe ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

plock - lock process, text, or data in memory 

SYNOPSIS 

ttinclude < ays/ lock. h> 

Int plock(int op); 

DESCRIPTION 

plock ( ) allows the calling process to lock the text segment of the process (text lock), its data segment 
(data lock), or both its text and data segment (process lock) into memory. Locked segments are immune to 
all routine swapping, plock ( ) also allows these segments to be unlocked. To use this call, the calling 
process must be a member of a privilege group allowing plock ( ) (see setpr ivgrp ( ) on getprivgrp(2)) 
or the effective user ID of the calling process must be a user having appropriate privileges, op specifies the 
following: 

PROCLOCK lock text and data segments into memory (process lock) 

TXTLOCK lock text segment into memory (text lock) 

DATLOCK lock data segment into memory (data lock) 

UNLOCK remove locks 

EXAMPLES 

The following call to plock ( ) locks the calling process in memory: 

plock (PROCLOCK) ; 

RETURN VALUE 

Upon successful completion, plock ( ) returns to the calling process. Otherwise, it returns -1 and sets 
errno to indicate the error. 

ERRORS 

plock ( ) fails and does not perform the requested operation if any of the following conditions are encoun- 
tered: 

[EPERM] The effective user ID of the calling process is not super-user and the user does not 

have the PRIV_MLOCK privilege. 

[EINVAL] op is equal to PROCLOCK and a process lock, a text lock, or a data lock already exists 

on the calling process. 

[EINVAL] op is equal to TXTLOCK and a text lock or process lock already exists on the calling 

process. 

[EINVAL] op is equal to DATLOCK and a data lock, or process lock already exists on the calling 

process. 

[EINVAL] op is equal to UNLOCK and no type of lock exists on the calling process. 

[EINVAL] op is not equal to either PROCLOCK, TXTLOCK, DATLOCK, or UNLOCK. 

[EINVAL] plock ( ) not allowed in [vfork, exec] window (see vfork(2)). 

[ENOMEM] There is not sufficient lockable memory in the system to satisfy the locking request. 

SEE ALSO 

exec(2), exit(2), fork(2). 

STANDARDS CONFORMANCE 

plock():SVTD2,XPG2 
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NAME 

poll - monitor I/O conditions on multiple file descriptors 

SYNOPSIS 

#include <poll.h> 

int poll( 

struct pollf d fds [ ] , 

int nfds, 

int timeout 
); 

DESCRIPTION 

poll ( ) provides a general mechanism for reporting I/O conditions associated with a set of file descriptors 
and for waiting until one or more specified conditions becomes true. Specified conditions include the ability 
to read or write data without blocking, and error conditions. 

Arguments 

fds Points to an array of pollf d structures, one for each file descriptor of interest. 

nfds Specifies the number of pol If d structures in the fds array. 

timeout Specifies the maximum length of time (in milliseconds) to wait for at least one of the 

specified conditions to occur. 

Each pol If d structure includes the following members: 

int f d File descriptor 

short events Requested conditions 
short revents Reported conditions 

The fd member of each pol If d structure specifies an open file descriptor. The poll() function uses 
the events member to determine what conditions to report for this file descriptor. If one or more of 
these conditions is true, poll ( ) sets the associated revents member. 

poll() ignores any pol If d structure whose fd member is negative. If the fd member of all 
pollf d structures is negative, poll ( ) returns and has no other results. 

The events and revents members of the pollf d structure are bit masks. The calling process sets 
the events bit mask, and poll() sets the revents bit masks. These bit masks contain ORed com- 
binations of condition flags. The following condition flags are defined: 

POLL IN Data can be read without blocking. For streams, this flag means that a mes- 

sage that is not high priority is at the front of the stream head read queue. 
This message can be of zero length. 

POLLNORM Synonym for POLLIN 

POLLPRI A high priority message is available. For streams, this message can be of zero 

length. 

POLLOUT Data can be written without blocking. For streams, this flag specifies that nor- 

mal data (not high priority or priority band > 0) can be written without being 
blocked by flow control. This flag is not used for high priority data, because it 
can be written even if the stream is flow controlled. 

POLLERR An error has occurred on the file descriptor. 

POLLEKJP The device has been disconnected. For streams, this flag in revents is 

mutually exclusive with POLLOUT, since a stream cannot be written to after a 
hangup occurs. This flag and POLLIN, POLLPRI, POLLRDNORM, POLLRD- 
BAND, and POLLMSG are not mutually exclusive. 

POLLNVAL f d is not a valid file descriptor. 

POLLRDNORM A non-priority message is available. For streams, this flag means that a nor- 

mal message (not high priority or priority band > 0) is at the front of the 
stream head read queue. This message can be of zero length. 

POLLRDBAND A priority message (priority band > 0) is at the front of the stream head read 

queue. This message can be read without blocking. The message can be of 
zero length. 



154 - 1 - HP-UX Release 9.0: August 1992 



poll ( 2 ) Series 300, 400, and 700 Only poll ( 2 ) 



POLLWRNORM Same as POLLOUT 

POLLWRBAND Priority data (priority band > 0) can be written without being blocked by flow 

control. Only previously written bands are checked. 
POLLMSG A M_SIG or M_PCSIG message specifying SIGPOLL has reached the front 

of the stream head read queue. 

The conditions indicated by POLLNORM and POLLOUT are true if and only if at least one byte of data 
can be read or written without blocking. The exception is regular files, which always poll true for 
POLLNORM and POLLOUT. Also, streams return POLLNORM in r events even if the available message 
is of zero length, 

The condition flags POLLERR, POLLHUP, and POLLNVAL are always set in revent s if the conditions 
they indicate are true for the specified file descriptor, whether or not these flags are set in events. 

For each call to poll ( ) , the set of reportable conditions for each file descriptor consists of those condi- 
tions that are always reported, together with any further conditions for which flags are set in events. If 
any reportable condition is true for any file descriptor, poll ( ) returns with flags set in revent s for 
each true condition for that file descriptor. 

If no reportable condition is true for any of the file descriptors, poll ( ) waits up to timeout milliseconds 
for a reportable condition to become true. If, in that time interval, a reportable condition becomes true for 
any of the file descriptors, poll ( ) reports the condition in the file descriptor's associated revents 
member and returns. If no reportable condition becomes true, poll() returns without setting any 
revents bit masks. 

If the timeout parameter is a value of -1, poll ( ) does not return until at least one specified event has 
occurred. If the value of the timeout parameter is 0, pol 1 ( ) does not wait for an event to occur but 
returns immediately, even if no specified event has occurred. The behavior of poll ( ) is not affected by 
whether the 0_NONBLOCK flag is set on any of the specified file descriptors. 

RETURN VALUES 

Upon successful completion, poll() returns a nonnegative value. If the call returns 0, poll() has 
timed out and has not set any of the revents bit masks. A positive value indicates the number of file 
descriptors for which poll ( ) has set the revents bit mask. If poll ( ) fails, it returns -1 and sets 
errno to indicate the error. 

ERRORS 

poll ( ) fails if any of the following conditions are encountered: 

[EAGAIN] . Allocation of internal data structures failed. A later call to poll ( ) may complete 

successfully. 

[EINTR] A signal was delivered before any of the selected for conditions occurred or before the 

time limit expired. 

[EINVAL] timeout is a negative number other than -1, or nfds is negative. 

[EFAULT] The fds parameter in conjunction with the nfds parameter addresses a location out- 

side of the allocated address space of the process. Reliable detection of this error is 
implementation-dependent. 

EXAMPLES 

Wait for input on file descriptor 0: 

ttinclude <poll.h> 
struct pollfd fds; 

fds.fd = 0; 

fds. events = POLLNORM; 

poll(&fds, 1, -1); 

Wait for input on If dl and If 6.2, output on of d, giving up after 10 seconds: 

# include <poll.h> 

struct pollfd fds [3]; 

int ifdl, ifd2, ofd, count; 

fds[0] .fd = ifdl; 
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fds[0] .events = POLLNORM; 

fds[l] .fd = ifd2; 

fds[l] .events = POLLNORM; 

fds[2].fd = ofd; 

fds [2] .events = POLLOUT; 

count = polKfds, 3, 10000); 

if (count == -1) { 

perror ( "poll failed" ) ; 

exit(l); 
> 
if ( count ==0) 

printf("No data for reading or writing\n"); 
if (fds[0] .revents & POLLNORM) 

printf ("There is data for reading fd %d\n", fds[0].fd); 
if (fds [1] .revents & POLLNORM) 

printf ("There is data for reading fd %d\n", fds[l].fd); 
if (fds [2] .revents & POLLOUT) 

printf ("There is room to write on fd %d\n", fds[2].fd); 

Check for input or output on file descriptor 5 without waiting: 

#include <poll.h> 
struct pollfd fds; 

fds.fd = 5; 

fds. events = POLLNORM | POLLOUT ; 

poll(&fds, 1, 0); 

if (fds. revents & POLLNORM) 

printf ("There is data available on fd %d\n", fds.fd); 
if (fds. revents & POLLOUT) 

printf ("There is room to write on fd %d\n", fds.fd); 

Wait 3.5 seconds: 

#include <stdio.h> 
#include <poll.h> 

poll ((struct pollfd *) NULL, 0, 3500); 

Wait for a high priority, priority, or normal message on streams file descriptor 0: 

ttinclude <poll.h> 
struct pollfd fds; 

fds.fd = 0; 

fds. events = POLLINIPOLLPRI; 
poll(&fds, 1, -IK- 
WARNINGS 

In some countries, electioneering is illegal within one hundred feet of a polling place. 

SEE ALSO 

read(2), write(2), select(2), getmsg(2), putmsg(2), streamio(7). 

STANDARDS CONFORMANCE 

poll():AES, SVID2 
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NAME 

prealloc - preallocate fast disk storage 

SYNOPSIS 

ttinclude <unistd.h> 

int prealloc (int flldes, off_t size); 

DESCRIPTION 

prealloc ( ) is used to preallocate space on a disk for faster storage operations. 

fildes is a file descriptor obtained from a creat ( ) , pen ( ) , dup ( ) , or f cntl ( ) system call for an ordi- 
nary file of zero length. It must be opened writable, because it will be written to by prealloc ( ) . size is 
the size in bytes to be preallocated for the file specified by fildes. At least size bytes will be allocated. Space 
is allocated in an implementation-dependent fashion for fast sequential reads and writes. The EOF in an 
extended file is left at the end of the preallocated area. The current file pointer is left at zero. The file is 
zero-filled. 

Using prealloc ( ) on a file does not give the file an attribute that is inherited when copying or restoring 
the file using a program such as cp or tar (see cp(l) and tar(l)). It simply ensures that disk space has 
been preallocated for size bytes in a manner suited for sequential access. The file can be extended beyond 
these limits by write ( ) operations past the original end of file. However, this space will not necessarily 
be allocated using any special strategy. 

EXAMPLES 

Assuming a process has opened a file for writing, the following call to prealloc ( ) preallocates at least 
50 000 bytes on disk for the file represented by file descriptor outfd: 

prealloc (outfd, 50000); 

DEPENDENCIES 

Since the exact effect and performance benefits obtainable by using this call vary with the implementation 
of the file system, performance related details are described in the system administrator manuals for each 
specific machine. 

RETURN VALUE 

Upon successful completion, prealloc ( ) returns 0; otherwise, it returns -1 and sets errno to indicate 
the error. 

ERRORS 

prealloc ( ) fails and no disk space is allocated if any of the following conditions are encountered: 

[EBADF] fildes is not a valid open file descriptor opened for writing. 

[EDQUOT] User's disk quota block limit has been reached for this file system. 

[EFBIG] size exceeds the maximum file size or the process's file size limit. See ulimit(2). 

[ENOSPC] Not enough space is left on the device to allocate the requested amount; no space was 

allocated. 

[ENOTEMPTY] fildes not associated with an ordinary file of zero length. 

AUTHOR 

prealloc ( ) was developed by HP. 

SEE ALSO 

prealloc(l), creat(2), dup(2), fcntl(2), open(2), read(2), ulimit(2), write(2). 

WARNINGS 

Allocation of the file space is highly dependent on current disk usage. A successful return does not tell you 
how fragmented the file actually might be if the disk is nearing its capacity. 
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NAME 

profil - execution time profile 

SYNOPSIS 

#include <time.h> 

void profil ( 

unsigned short int *buff ; 

size_t bufsiz, 

size_t offset, 

unsigned int scale 
); 

DESCRIPTION 

profil ( ) controls profiling, by which the system maintains estimates of the amount of time the calling 
program spends executing at various places in its address space. 

The buff argument must point to an area of memory whose length (in bytes) is given by bufsiz. When 
profiling is on, the process's program counter (pc) is examined each clock tick (CLK_TCK times per second), 
offset is subtracted from the pc value, and the result is multiplied by scale. If the resulting number 
corresponds to an element inside the array of unsigned short ints to which buff points, that element 
is incremented. 

The number of samples per second for a given implementation is given by CLK_TCK, which is defined in 
<time.h>. 

The scale is interpreted as an unsigned, sixteen bit, fixed-point fraction with binary point at the left: 
0177777 (octal) gives a one-to-one mapping of pc's to words in buff; 077777 (octal) maps each pair of instruc- 
tion words together. 02(octal) maps all instructions onto the beginning of buff (producing a non- 
interrupting core clock). 

Profiling is turned off by giving a scale of or 1. It is rendered ineffective by giving a bufsiz of 0. Profiling 
is turned off when one of the exec ( ) functions is executed, but remains on in child and parent both after 
a fork ( ) . Profiling is turned off if an update in buff would cause a memory fault. 

RETURN VALUE 

No value is returned. 

SEE ALSO 

prof(l), monitor(3C). 

STANDARDS CONFORMANCE 

profil ( ) : SVID2, XPG2 
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NAME 

ptrace - process trace 

SYNOPSIS 

#include <sys/ptrace.h> 

int ptrace ( 

int request, 

pid_t pid, 

int addr, 

int data, 

int addr 2 
); 

REMARKS 

Much of the functionality of this capability is highly dependent on the underlying hardware. An application 
that uses this system call should not be expected to be portable across architectures or implementations. 

DESCRIPTION 

ptrace ( ) provides a means by which a process can control the execution of another process. Its primary 
use is for the implementation of breakpoint debugging; see adb(l). The traced process behaves normally 
until it encounters a signal (see signal(2) for the list), at which time it enters a stopped state and the trac- 
ing process is notified via wait ( ) (see wait(2)). When the traced process is in the stopped state, the trac- 
ing process can examine and modify the "core image" using ptrace ( ) . Also, the tracing process can cause 
the traced process either to terminate or continue, with the possibility of ignoring the signal that caused it 
to stop. 

The request argument determines the precise action to be taken by ptrace ( ) and is one of the following: 

PT_SETTRC This request must be issued by a child process if it is to be traced by its parent. It 
turns on the child's trace flag which stipulates that the child should be left in a 
stopped state upon receipt of a signal rather than the state specified by func; see sig- 
nal(2). The pid, addr, data, and addr2 arguments are ignored, and a return value is 
not defined for this request. Peculiar results occur if the parent does not expect to 
trace the child. 

The remainder of the requests can only be used by the tracing process. For each, pid is the process ID of 
the process being traced, which must be in a stopped state before these requests are made. 

PT_RIUSER, PT_RDUSER 

With these requests, the word at location addr in the address space of the traced 
process is returned to the tracing process. If instruction (I) and data (D) space are 
separated, request PT_RIUSER returns a word from I space, and request 
PT_RDUSER returns a word from D space. If I and D space are not separated, 
either request PT_RIUSER or request PT_RDUSER can be used with equivalent 
results. The data and addr2 arguments are ignored. These two requests fail if 
addr is not the start address of a word, in which case a value of -1 is returned to the 
tracing process and its errno is set to EIO. 

PTJRUAREA With this request, the word at location addr in the USER area of the traced process 
in the system's address space (see <sys/user .h>) is returned to the tracing pro- 
cess. Addresses in this area are system dependent, but start at zero. The limit can 
be derived from <sys/user.h>. The data and addr2 arguments are ignored. 
This request fails if addr is not the start address of a word or is outside the USER 
area, in which case a value of -1 is returned to the tracing process and its errno is 
set to EIO. 

PT_WIUSER, PTJWDUSER 

With these requests, the value given by the data argument is written into the 
address space of the traced process at location addr. Request PTJWIUSER writes 
a word into I space, and request PT_WDUSER writes a word in D space. Upon suc- 
cessful completion, the value written into the address space of the traced process is 
returned to the tracing process. The addr2 argument is ignored. These two 
requests fail if addr is not the start address of a word, or if addr is a location in a 
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pure procedure space and either another process is executing in that space or the 
tracing process does not have write access for the executable file corresponding to 
that space. Upon failure a value of -1 is returned to the tracing process and its 
errno is set to EIO. 

PT_WUAREA With this request, a few entries in the traced process' USER area can be written. 
data sives the value that is to be written and addr is the location of the entr* 7 . The 
addr2 argument is ignored. The few entries that can be written are dependent on 
the architecture of the system, but include the user data registers, auxiliary data 
registers, and status register (the set of registers, or bits in registers, that the user's 
program could modify). 

PT_CONTIN This request causes the traced process to resume execution. If the data argument is 
0, all pending signals, including the one that caused the traced process to stop, are 
canceled before it resumes execution. If the data argument is a valid signal 
number, the traced process resumes execution as if it had incurred that signal, and 
any other pending signals are canceled. The addr argument must be equal to 1 for 
this request. The addr2 argument is ignored. Upon successful completion, the 
value of data is returned to the tracing process. This request fails if data is not or 
a valid signal number, in which case a value of -1 is returned to the tracing process 
and its errno is set to EIO. 

PT_EXIT This request causes the traced process to terminate with the same consequences as 

exit ( ) . The addr, data, and addr2 arguments are ignored. 

PT_SINGLE This request causes a flag to be set so that an interrupt occurs uponthe completion 
of one machine instruction, and then executes the same steps as fisted above for 
request PT_CONTIN. If the processor does not provide a trace bit, this request 
returns an error. This effectively allows single stepping of the traced process. 

Whether or not the trace bit remains set after this interrupt is a function of the 
hardware. 

PT_ATTACH This request stops the process identified by pid and allows the calling process to 
trace it. Process pid does not have to be a child of the calling process, but the 
effective user ID of the calling process must match the real and saved uid of process 
pid unless the effective user ID of the tracing process is super-user. The calling pro- 
cess can use the wait ( ) system call to wait for process pid to stop. The addr, 
data, and addr2 arguments are ignored. 

PTJDETACH This request detaches the traced process pid and allows it to continue its execution 
in the manner of PT_CONTIN. 

To forestall possible fraud, ptrace ( ) inhibits the set-user-ID facility on subsequent exec ( ) calls. If 
a traced process calls exec ( ) , it stops before executing the first instruction of the new image showing 
signal SIGTRAP. 

ERRORS 

In general, ptrace ( ) fails if any of the following conditions are encountered: 

[EIO] request is an illegal number. 

[EPERM] The specified process cannot be attached for tracing. 

[ESRCH] pid identifies a process to be traced that does not exist or has not executed 

a ptrace () with request PT_SETTRC. 

DEPENDENCIES 
Series 300/400 

The following additional requests are available: 

PT_RPPREGS With this request, the child's floating-point accelerator register set is returned to the 
parent process in addr. addr must be the address of a buffer of at least 136 bytes. 
The first 128 bytes contains the 16 double-precision floating-point registers and the 
next 8 bytes contains the status and control registers. The data argument is ignored. 
This request fails if the child process is not using the floating-point accelerator, in 
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which case a value of -1 is returned to the parent process and the parent's errno is 
set to EIO. This request also fails if addr is a bad address, in which case a value of -1 
is returned to the parent process and the parent's errno is set to EFAULT. 

PT_WPPREGS With this request, the child's floating-point accelerator register set is written from the 
buffer pointed to by addr. addr must be the address of a buffer of at least 136 bytes. 
The first 128 bytes contains the new values for the 16 double-precision floating point 
registers and the next 8 bytes contains the new values for the status and control 
registers. The data argument is ignored. This request fails if the child process is not 
using the floating-point accelerator, in which case a value of -1 is returned to the 
parent process and the parent's errno is set to EIO. This request also fails if addr is 
a bad address, in which case a value of -1 is returned to the parent process and the 
parent's errno is set to EFAULT. 

Series 700/800 

The request PT_WUAREA is not supported. Therefore, it returns -1, sets errno to EIO and does not affect 
the USER area of the traced process. 

If the addr argument to a PT_CONTIN or PT_S INGLE request is not 1, the Instruction Address Offset 
Queue (program counter) is loaded with the values addr and addr+4 before execution resumes. Otherwise, 
execution resumes from the point where it was interrupted. 

If the addr argument to a PT_DETACH request is not 1, the Instruction Address Offset Queue is loaded 
with the values addr and addr2. 

Additional requests are available: 

PT_RUREGS With this request, the word at location addr in the save_state structure at the 
base of the per-process kernel stack is returned to the tracing process, addr must be 
word-aligned and less than STACKS I ZE *NBPG (see <sys/param.h> and 
<tnachine/param.h>). The save_state structure contains the registers and 
other information about the process. The data and addr2 arguments are ignored. 

PTJWUREGS The save_state structure at the base of the per-process kernel stack is written as 
it is read with request PT_RUREGS. Only a few locations can be written in this way: 
the general registers, most floating-point registers, a few control registers, and certain 
bits of the interruption processor status word. The addr2 argument is ignored. 

PT_RDTEXT, PT_RDDATA 

These requests are identical to PT_RIUSER and PT_RDUSER, except that the data 
argument specifies the number of bytes to read and the addr2 argument specifies 
where to store that data in the tracing process. 

PTJWRTEXT , PT_WRDATA 

These requests are identical to PTJWIUSER and PT_WDUSER except that the data 
argument specifies the number of bytes to write and the addr2 argument specifies 
where to read that data in the tracing process. 

SEE ALSO 

adb(l), exec(2), signal(2), wait(2). 

STANDARDS CONFORMANCE 

ptrace ( ) : SVID2, XPG2 
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NAME 

quotactl - manipulate disk quotas 

SYNOPSIS 

#include <sys/guota.h> 

int quotactl (int cmd, const char *special, uid_t uid, void *addr) ; 

DESCRIPTION 

quotactl () manipulates disk quotas, cmd indicates a command to be applied to the user ID uid. 
Parameter special is a pointer to a null-terminated string containing the path name of the block special dev- 
ice for the file system being manipulated. The block special device must be mounted as an hfs file system 
(see mount(2)). The parameter addr is the address of an optional, command-specific, data structure which 
is copied in or out of the system. The interpretation of addr is explained with each command below: 

Q_QUOTAON Turn on quotas for a file system. The parameter addr points to the path name of file 
containing the quotas for the file system. The quota file must exist; it is normally 
created using the quotacheck command (see quotacheck(lM)). The uid parameter 
is ignored. This call is restricted to users having appropriate privileges. 

Q_QUOTAOPP Turn off quotas for a file system. The addr and uid parameters are ignored. This call 
is restricted to the user with appropriate privileges. 

Q_GETQUOTA Get disk quota limits and current usage for user uid. addr is a pointer to a dqblk 
structure (defined in <sys /quota . h>). Only users having appropriate privileges 
can get the quotas of a user other than himself. 

Q_SETQUOTA Set disk quota limits and current usage of files and blocks for user uid. addr is a 
pointer to a dqblk structure (defined in <sys /quota. h>). This call is restricted 
to users with appropriate privileges. 

Q_SETQLIM Set disk quota limits for user uid. The parameter addr is a pointer to a dqblk 
structure (defined in <sys /quota. h>). This call is restricted to users with 
appropriate privileges. 

Q_SYNC Update the on-disk copy of quota usages for a file system. If special is null, all file 

systems with active quotas are synced. The parameters addr and uid are ignored. 

RETURN VALUE 

Upon successful completion, quotactl ( ) returns 0; otherwise, it returns -1 and sets errno to indicate 
the error. 

ERRORS 

quotactl ( ) fails when any of the following occurs: 

[ENOSYS] The kernel has not been configured with the disk quota subsystem. 

[EINVAL] The parameter cmd is invalid. 

[ESRCH] No disc quota is found for the indicated user or quotas have not been turned on for 

this file system. 

[EPERM] The call is privileged and the calling process does not have appropriate privileges. 

[ENODEV] The parameter special is not a mounted HFS file system. 

[ENOTBLK] The parameter special is not a block device. 

[EACCES] (Q_QUOTAON) The quota file pointed to by addr exists but is either not a regular file 

or is not on the file system pointed to by special. 

[EBUSY] Q_QUOTAON attempted while another Q_QUOTAON or Q_QUOTAOFF is in progress. 

[ENOENT] The file specified by special or addr does not exist. 

[EFAULT] The addr or special parameter points to an invalid address. Reliable detection of this 

error is implementation-dependent. 

[EDQUOT] User's disk quota block limit has been reached for this file system. 
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WARNINGS 

The quotactl ( ) system call is incompatible with the 4.2/4.3BSD implementation of Melbourne quotas 
which uses a different system call interface and on-disk data structure. 

AUTHOR 

quotactl ( ) was developed by HP and Sun Microsystems, Inc. 

SEE ALSO 

quota (1), edquota (1M), rquotad (1M), quotacheck (1M), quotaon (1M), mount (2), quota (5), privileged). 
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NAME 

read, readv - read input 

SYNOPSIS 

ttinclude <unistd.h> 



size_t read(int fildes, void *buf, size_t nbyte) ; 



ssize_t readv ( 

lnt fildes, 

const struct iovec *iov, 

size_t iovcnt 
); 

DESCRIPTION 

read ( ) attempts to read nbyte bytes from the file associated with the file descriptor into the buffer pointed 
to by buf. readv ( ) performs the same action, but scatters the input data into the iovcnt buffers specified 
by the elements of the iovec array: iov[0], iov [1], ..., iov[iovcnt - 1 ]. 

For readv ( ) , the iovec structure is defined as: 

struct iovec { 

caddr_t i ov_bas e ; 

int iov_len; 
}; 

Each iovec entry specifies the base address and length of an area in memory where data should be 
placed, readv () always fills one area completely before proceeding to the next area. The iovec array 
can be at most MAXIOV long. 

On devices capable of seeking, the read ( ) starts at a position in the file given by the file offset associated 
with fildes. Upon return from read ( ) , the file offset is incremented by the number of bytes actually read. 

Devices incapable of seeking always read from the current position. The value of a file offset associated 
with such a device is undefined. 

When attempting to read from a regular file with enforcement-mode file and record locking set (see 
chmod(2)), and the segment of the file to be read is blocked by a write lock owned by another process, the 
behavior is determined by the 0_NDELAY and 0_NONBLOCK file status flags: 

• If 0_NDELAY or 0_NONBLOCK is set, read ( ) returns -1 and errno is set to EAGAIN. 

• If 0_NDELAY and 0_NONBLOCK are clear, read ( ) does not return until the blocking write 
lock is removed. 

When attempting to read from an empty pipe (or FIFO): 

• If no process has the pipe open for writing, the read returns a 0. 

• If some process has the pipe open for writing and 0_NONBLOCK is set, the read returns -1 and 
errno is set to EAGAIN. 

• If 0_NDELAY is set, the read returns a 0. 

• If some process has the pipe open for writing and 0_NDELAY and 0_NONBLOCK are clear, the 
read blocks until data is written to the file or the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data currently available: 

• If 0_NONBLOCK is set, the read returns -1 and errno is set to EAGAIN. 

• If 0_NDELAY is set, the read returns 0. 

• If 0_NDELAY and 0_NONBLOCK are clear, the read blocks until data becomes available. 

If read ( ) is interrupted by a signal after it has successfully read some data, it returns the number of 
bytes actually read and placed in the buffer before the interrupt occurred. If read ( ) is interrupted 
before any data is successfully read, read ( ) returns -1 and sets errno to EINTR. 
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RETURN VALUE 

Upon successful completion, read ( ) returns the number of bytes actually read and placed in the buffer; 
this number may be less than nbyte if: 

• The file is associated with a communication line (see ioctl(2) and termioil)), or 

• The number of bytes left in the file is less than nbyte bytes. 

• read ( ) was interrupted by a signal after it had successfully read some, but not all of the data 
requested. 

When an end-of-file is reached, a value of is returned. Otherwise, a -1 is returned and errno is set to 
indicate the error. 

ERRORS 

read ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid file descriptor open for reading. 

[EINTR] A signal was caught before any data was transferred (see sigvector(2)). 

[EAGAIN] Enforcement-mode file and record locking is set, 0_NDELAY or 0_NONBLOCK is set, 

and there is a blocking write lock. 

[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and 

fcntl(2)). 

[EFAULT] buf points outside the allocated address space. Reliable detection of this error is 

implementation dependent. 

[EIO] The process is in a background process group and is attempting to read from its con- 

trolling terminal, and either the process is ignoring or blocking the SIGTTIN signal 
or the process group of the process is orphaned. 

[EIO] An I/O error occurred while reading from the device corresponding to fildes. 

[EISDIR] An attempt was made to read a directory on an NFS file system using the read ( ) 

system call. 

[ENOLCK] The system record lock table is full, preventing the read from sleeping until the block- 

ing write lock is removed. 

In addition, readv ( ) can return one of the following errors: 

[EFAULT] iov_ba.se or iov points outside of the allocated address space. The reliable detection 

of this error is implementation dependent. 

[EINVAL] iovcnt is less then or equal to 0, or greater than MAXIOV. 

[EINVAL] The sum of iov Jen values in the iov array exceeded UINT_MAX defined in 

<limits . h> (see limits(5)). 

EXAMPLES 

Assuming a process opened a file for reading, the following call to read{2) reads BUPSIZ bytes from the file 
into the buffer pointed to by mybuf: 

#include <stdio.h> /* Include this for BUPSIZ definition */ 

char mybuf [BUPSIZ] ; 
int nbytes, fildes; 

nbytes = read (fildes, mybuf, BUPSIZ); 

WARNINGS 

Record locking might not be enforced by the system, depending on the setting of the file's mode bits (see 
lockf(2)). 

Character-special devices, and raw disks in particular, apply constraints on how read ( ) can be used. See 
the specific Section (7) entries for details on particular devices. 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector ( ) 
can affect the behavior described on this page. 
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In general, avoid using read ( ) to get the contents of a directory; use the readdlr ( ) library routine 
(see directory (3C)). 

DEPENDENCIES 

NFS 

When obtaining the contents of a directory on an NFS file system, the readdir ( ) library routine must be 
used (see directory (3C)). read ( ) returns with an error if used to read a directory using NFS. 

AUTHOR 

read ( ) was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2), lockf(2), open(2), pipe(2), select(2), ustat(2), tty(7), directory(3C). 

STANDARDS CONFORMANCE 

read ( ) : AES, SVID2, XPG2, XPG3, XPG4, FTPS 151-2, POSIX.l 
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NAME 

readlink - read value of a symbolic link 

SYNOPSIS 

ttinclude <symlink.h> 

ssize_t readlink ( 

const char *path, 

char *buf, 

size_t bufsiz 
) ; 

DESCRIPTION 

readlink ( ) obtains the path name pointed to by the symbolic link, path. This path name is placed in 
the buffer buf, which has size bufsiz. 

RETURN VALUE 

If readlink( ) succeeds, it returns the count of characters placed in the buffer. If an error occurs, it 
returns -1 and sets errno to indicate the error. 

ERRORS 

readlink ( ) fails if any of the following conditions is encountered: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENAMETOOLONG] A component of path exceeds bytes while is in effect, or path exceeds bytes. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[ELOOP] Too many symbolic finks were encountered in translating the path name. 

[EINVAL] The named file is not a symbolic link. 

[EFAULT] buf points outside the process' allocated address space. Reliable detection of this 

error is implemenation dependent. 

DEPENDENCIES 

Series 300,400, and 700: 

If the length of the path name string is less than bufsiz, the string will be null terminated when returned. 
If the length of the path name string is exactly bufsiz, the string will not be null terminated when returned. 
If the length of the path name string exceeds bufsiz, readl ink ( ) returns -1 and sets errno to: 

[ERANGE] The length of the path name string read from the symbolic link exceeds bufsiz. 

Series 800: 

The path name is not null terminated when returned. 

AUTHOR 

readlink ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

stat(2), lstat(2), symlink(2), symlink(4). 

STANDARDS CONFORMANCE 

readlink ( ) : AES [Series 300/400/700 only] 



HP-UX Release 9.0: August 1992 - 1 - 167 



reboot(2) reboot(2) 



NAME 

reboot - boot the system 

SYNOPSIS 

#include < sys/ reboot .h> 

int reboot (int howto, ... 

/* const char *d.evice_f ile, 

const char ♦filename, 

const char *filename, 

const char *server_linkaddress */ 
); 

DESCRIPTION 

reboot () causes the system to reboot, howto is a mask of reboot options (see <sys /reboot .h>), 
specified as follows: 

RB_AUTOBOOT A file system sync is performed (unless RB_NOSYNC is set) and the processor is 

rebooted from the default device and file. 

RB_HALT The processor is simply halted. A sync of the file system is performed unless the 

RB_NOSYNC flag is set. RB_HALT should be used with caution. 

RB_NOS YNC A sync of the file system is not performed. 

RB_NEWDEVICE The device_file argument is used as the file name of the device from which to 
reboot. 

RB_NEWPILE The filename argument is used as the name of the file being rebooted. 

RB_NEWSERVER The additional optional parameter, server Jinkaddress, specifies the ETHERNET 
link address of a new boot server. The server Jinkaddress is a 12-character hex- 
adecimal number that has the same format as the machine ID field of 
/etc/clusterconf . The Ox prefix is optional. 

This allows a standalone system or HP cluster server to reboot and join an HP 
cluster as a client node, or for an existing client to join a different HP cluster. 

device _file specifies the "boot device", the device from which the reboot occurs, device _file must be a block 
or character special file name and is used only if the RB_NEWDEVICE option is set. 

If the RB_NEWPILE option is set, filename specifies the "boot file", the name of the file being rebooted. 
This file is loaded into memory by the bootstrap then control is passed to it. 

If the RB_NEWSERVER option is set, reboot(2) does not verify that server Jinkaddress is a valid ETHER- 
NET address, nor that the specified server is valid or provides the required service. 

If the boot device is not a LAN device, the server Jinkaddress information is ignored. The boot device is 
considered a LAN device if the previous boot was from a LAN device or if a IAN device is specified via the 
RB_NEWDEVICE option. 

Unless the RB_NOSYNC flag has been specified, reboot(2) unmounts all mounted file systems and marks 
them clean so that it will not be necessary to run fsck(lM) on these file systems when the system reboots. 

Only users with appropriate privileges can reboot a machine. 

RETURN VALUE 

If successful, this call never returns. Otherwise, a -1 is returned and errno is set to indicate the error. 

ERRORS 

reboot ( ) fails if any of the following conditions are encountered: 

[EFAULT] device Jile points outside the allocated address space of the process. 

[ENAMETOOLONG] the path name specified by device Jile exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[EINVAL] device Jile is not a block or a character device. 
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[ENET] The device specified by device_file is remote. 

[ENOENT] The file specified by devicejile does not exist. 

[ENOTDIR] A component of the path prefix specified by devicejile is not a directory. 

[ENXIO] The device named by devicejile does not exist. 

[EPERM] The effective user ID of the caller is not a user with appropriate privileges. 

DEPENDENCIES 
Series 300/400 

filename must be one of the files fisted by the boot ROM at power-up. 

The default device, file, and server for RB_AUTOBOOT are those from which the system was previously 
booted. 

If the RB_NEWDEVICE option is used and devicejile specifies a LAN device, the RB_NEWSERVER option 
and server Jinkaddr ess parameter must also be used. 

If an invalid server Jinkaddress is specified with the RB_NEWSERVER option, or if the requested server 
does not respond, the Series 300/400 boot ROM displays the message BOOTING A SYSTEM and retries 
indefinitely, or until the requested server responds, or the system is rebooted manually. 

Series 700/800 

The RB_NEWDEVICE, RB_NEWPILE, and RB_NEWSERVER options and the devicejile, filename and 
server Jinkaddress parameters are ignored. Therefore, none of the errors associated with them are 
returned. 

The default file and device for RB_AUTOBOOT are /hp-ux on the current root device. 

AUTHOR 

reboot ( ) was developed by HP and the University of California, Berkeley. 

SEE ALSO 

reboot(lM), clusterconf(4). 
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NAME 

recv, recvfrom, recvmsg - receive a message from a socket 

SYNOPSIS 

#include < sys/ socket .h> 

int recv(int s, void *buf, int len, int flags); 

int recvfrom ( 
int s, 
void *buf, 
int len, 
int flags, 
void ♦from, 
int *f romlen) ; 

int recvmsgdnt s, struct msghdr msg[], int flags); 

DESCRIPTION 

recv ( ) , recvfrom ( ) , and recvmsg ( ) are used to receive messages from a socket. 

s is a socket descriptor from which messages are received, buf is a pointer to the buffer into which the mes- 
sages are placed, len is the maximum number of bytes that can fit in the buffer referenced by buf. 

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be 
used after the connection has been established (see connect(2)). For connectionless sockets such as 
SOCKJDGRAM, these calls can be used whether a connection has been specified or not. 

recvfrom ( ) operates in the same manner as recv ( ) except that it is able to return the address of the 
socket from which the message was sent. For connected datagram sockets, recvfrom ( ) simply returns 
the same address as getpeername ( ) (see getpeername(2)). For stream sockets, recvfrom () 
retrieves data in the same manner as recv ( ) , but does not return the socket address of the sender. If 
from is non-zero, the source address of the message is placed in the socket address structure pointed to by 
from, fromlen is a value-result parameter, initialized to the size of the structure associated with from, and 
modified on return to indicate the actual size of the address stored there. If the memory pointed to by from 
is not large enough to contain the entire address, only the first fromlen bytes of the address are returned. 

The length of the message is returned. 

For message-based sockets such as SOCKJJGRAM, the entire message must be read in a single operation. If 
a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets 
such as SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user 
as soon as it becomes available, and no data is discarded. See the AF_CCITT section below for a list of the 
exceptions to this behavior for connections in the address family AF_CCITT. 

recvmsg ( ) performs the same action as recv ( ) , but scatters the read data into the buffers specified in 
the msghdr structure. This structure is defined in <sys /socket . h>, and has the following form : 

struct msghdr { 

caddr_t msg_name; /* optional address */ 

int msg_namelen; /* size of address */ 

struct iovec *msg_iov; /* scatter array for data */ 

int msg_iovlen; /* # of elements in msg_iov */ 

caddr_t msg_accrights; /* access rights */ 

int msg_accrightslen; /* size of msg_accrights */ 

} 

msg_name is the destination address if the socket is unconnected; msgjtame may be a null pointer if no 
name is specified. msg_iov is the location of the scatter/gather data, msgjxccrights specifies a buffer to 
receive any access rights sent along with the message. Access rights are limited to file descriptors of size 
int. If access rights are not being transferred, set the msg_acccrights field to NULL. Access rights are sup- 
ported only for AFJJNIX. 

If no data is available to be received, recv ( ) waits for a message to arrive unless non-blocking mode is 
enabled. There are three ways to enable non-blocking mode: 
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• With the FIOSNBIO ioctl () request, 

• With the 0_NONBLOCK fcntl() flag, 

• With the 0_NDELAY fcntl() flag. 

If non-blocking I/O is enabled using PIOSNBIO or the equivalent PIONBIO request (defined in 
<sys/ioctl.h> and explained in ioctl(2), ioctl(5) and socket(7), although use of PIONBIO is not 
recommended), the recv ( ) request completes in one of three ways: 

• If there is enough data available to satisfy the entire request, recv ( ) completes successfully, 
having read all of the data, and returns the number of bytes read. 

• If there is not enough data available to satisfy the entire request, recv ( ) complete success- 
fully, having read as much data as possible, and returns the number of bytes it was able to read. 

• If there is no data available, recv ( ) fails and errno is set to EWOULDBLOCK. 

If non-blocking I/O is disabled using PIOSNBIO, recv ( ) always executes completely (blocking as neces- 
sary) and returns the number of bytes read. 

If the 0_NONBLOCK flag is set using f cntl ( ) (defined in <sys/f cntl .h> and explained in fcntl(2) 
and/bwfZ(5)), POSDC-style non-blocking I/O is enabled. In this case, the recv() request completes in one 
of three ways: 

• If there is enough data available to satisfy the entire request, recv ( ) completes successfully, 
having read all the data, and returns the number of bytes read. 

• If there is not enough data available to satisfy the entire request, recv ( ) completes success- 
fully, having read as much data as possible, and returns the number of bytes it was able to read. 

• If there is no data available, recv ( ) completes, having read no data, and returns -1 with 
errno set to EAGAIN. 

If the 0_NDE LAY flag is set using f cntl ( ) (defined in <sys / f cnt 1 .h> and explained in fcntl(2) and 
fcntl(5)\ non-blocking I/O is enabled. In this case, the recv() request completes in one of three ways: 

• If there is enough data available to satisfy the entire request, recv ( ) completes successfully, 
having read all the data, and returns the number of bytes read. 

• If there is not enough data available to satisfy the entire request, recv ( ) completes success- 
fully, having read as much data as possible, and returns the number of bytes it was able to read. 

• If there is no data available, recv( ) completes successfully, having read no data, and returns 
0. 

If the 0_NONBLOCK or 0_NDELAY flag is cleared using f cntl ( ) , the corresponding style of non- 
blocking I/O, if previously enabled, is disabled. In this case, recv() always executes completely (block- 
ing as necessary) and returns the number of bytes read. 

Since both the fcntl() 0_NONBLOCK and 0_NDELAY flags and loctl () PIOSNBIO request are 
supported, some clarification on how these features interact is necessary. If the 0_NONBLOCK or 
0_NDELAY flag has been set, recv() requests behave accordingly, regardless of any FIOSNBIO 
requests. If neither the 0_NONBLOCK nor 0_NDE LAY flag has been set, PIOSNBIO requests control 
the behavior of recv ( ) . The default is that non-blocking I/O is not enabled. 

select ( ) can be used to determine when more data arrives by selecting the socket for reading. 

The flags parameter can be set to MSG_PEEK, MSG_OOB, both, or zero. If it is set to MSG_PEEK, any 
data returned to the user still is treated as if it had not been read. The next recv ( ) re-reads the same 
data. The MSG_OOB flag is used to alert the other process with an urgent message, using a logically 
independent transmission channel associated with a pair of connected stream sockets. Refer to SEE ALSO 
below for details. For stream-based TCP SOCK.STREAM sockets, both the MSGJPEEK and MSG_OOB 
flags can be set at the same time. The MSG_OOB flag value is supported for stream-based TCP 
SOCK.STREAM sockets only. MSG_OOB is not supported for AFJJNIX sockets. 

A read ( ) call made to a socket behaves in exactly the same way as a recv ( ) with flags set to zero. 

AF_CCITT only: 

Connections in the address family AF_CCITT support message-based sockets only. Although the user 
specifies connection-based communications (SOCK_STREAM), the X.25 subsystem communicates via 
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messages. This address family does not support SOCK.DGRAM socket types. 

Normally, each recv ( ) returns one complete X.25 message. If the socket is in non-blocking mode, 
recv() behaves as described above. Note that if the user specifies len less than the actual X.25 message 
size, the excess data and no error indication is returned. The size of the next available message as well as the 
state of MDTF, D, and Q bits can be obtained with ioctl (X2 5_NEXT_MSG_STAT) . 

Connections of the address family AF_CCITT receive data in the same way as message-based connections 
described above, with the following additions and exceptions: 

• recvfromO is supported; however, the from and fromlen parameters are ignored (that is, it 
works in the same manner as recv ( ) ). 

• To receive a message in fragments of the complete X.25 message, use 
ioctl (X25_SET_I 
ment of the message. 

• The MSG_OOB flag is supported. 

• The MSG_PEEK flag is supported; the two flags can be combined. 

• If a message is received that is larger than the user-controlled maximum message size (see 
af_ccitt(7F)\ the X.25 subsystem RESETS the circuit, discards the data, and sends the out-of-band 
event OOB_VC_MESSAGE_TOO_BIG to the socket. 

DEPENDENCIES 
AFCCITT 

recvfromO is supported; however, the from and fromlen parameters are ignored (i.e., it works in the 
same manner as recv ( ) ). 

The 0_NDELAY fcntl() call is not supported over X.25 links. Use the PIOSNBIO ioctl () call 
instead to enable non-blocking I/O. 

RETURN VALUE 

upon successful completion, recv ( ) returns the number of bytes received. Otherwise, it returns -1 and 
sets errno to indicate the error. recv( ) returns if the socket is blocking and the transport connec- 
tion to the remote node fails. 

DIAGNOSTICS 

The call to recv() or recvfromO fails if any of the following conditions are encountered: 

[EBADF] The argument s is an invalid descriptor. 

[ENOTSOCK] The argument s is not a socket. 

[EWOULDBLOCK] The socket is marked non-blocking and the receive operation would block. 

[EINTR] The receive was interrupted by delivery of a signal before any data was avail- 

able for the receive. 

[EFAULT] An invalid pointer was specified in the buf , from , or fromlen parameter, or in 

the msghdr structure. 

[EMSGSIZE] A length in the msghdr structure is invalid. 

[ETIMEDOUT] The connection timed out during connection establishment, or due to a transmis- 

sion timeout on active connection. 

[ENOTCONN] Receive on a SOCKJSTREAM socket that is not yet connected. 

[EINVAL] The len parameter or a length in the msghdr structure is invalid; or no data is 

available on receive of out of band data. 

[EOPNOTSUPP] The MSG_OOB flag was set for a UDP SOCK.DGRAM message-based socket; or 

MSG_OOB or MSG_PEEK was set for any AF.UNIX socket. The MSG_OOB flag 
is only supported for stream-based TCP SOCK.STREAM sockets. Neither 
MSG_PEEK nor MSG_OOB is supported for AFJUNIX sockets. 

AF_CCITT Only: recv() was issued on a listen () socket. 



172 -3- HP-UX Release 9.0: August 1992 



recv(2) recv(2) 



[ENOBUFS] Insufficient resources were available in the system to perform the operation. 

[ECONNRESET] A connection was forcibly closed by a peer. 

AUTHOR 

recv ( ) was developed by the University of California, Berkeley 

SEE ALSO 

getsockopt(2), read(2), select(2), send(2), socket(2), af_ccitt(7F), inet(7F), socket(7), socketx25(7), tcp(7P), 
udp(7P), unix(7P). 
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NAME 

rename - change the name of a file 

SYNOPSIS 

#include <stdio.h> 

int rename (const char *source # const char *target) ; 

DESCRIPTION 

rename ( ) causes file source to be renamed to target. If target exists, it is first removed. Both source and 
target must be of the same type (that is, either directories or non-directories), and must reside on the same 
file system. 

If target can be created or if it existed before the call, rename ( ) guarantees that an instance of target will 
exist, even if the system crashes in the midst of the operation. 

If the final component of source is a symbolic link, the symbolic fink is renamed; not the file or directory to 
which the symbolic fink points. 

RETURN VALUE 

If the operation succeeds, rename ( ) returns 0; otherwise it returns -1 and sets errno to indicate the 
reason for the failure. 

ERRORS 

rename ( ) fails and neither file is affected if any of the following conditions are encountered: 



[EACCES] 
[EACCES] 
[EBUSY] 

[EDQUOTJ 

[EEXIST] 

[EFAULT] 

[EINVAL] 
[EISDIR] 
[ELOOP] 
[ENAMETOOLONG] 

[ENOENT] 

[ENOSPC] 

[ENOTDIR] 
[ENOTDIR] 

[EPERM] 

[EROFS] 

fEXDEV] 



A component of either path prefix denies search permission. 

The requested link requires writing to a directory without write permission. 

target or source is an existing directory that is the mount point for a mounted 
file system. 

User's disk quota block or mode limit has been reached for this file system. 

target is a directory and is not empty. 

source or target points outside the allocated address space of the process. Reli- 
able detection of this error is implementation dependent. 

source is a parent directory of target, or an attempt is made to rename . or . . . 

target is a directory, but source is not. 

Too many symbolic links were encountered in translating either path name. 

A component of either path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect, or the entire length of either path name 
exceeds PATH_MAX bytes. 

A component of the source path does not exist, or a path prefix of target does not 
exist. 

The destination directory cannot be extended because of a lack of space on the 
file system containing the directory. 

A component of either path prefix is not a directory. 

source is a directory, but target is not. [EPERM] The directory containing source 
has the sticky bit set, and neither the containing directory nor the source are 
owned by the effective user ID. 

The target file exists, the directory containing target has the sticky bit set, and 
neither the containing directory nor the target are owned by the effective user 
ID. 

The requested link requires writing in a directory on a read-only file system. 

The paths named by source and target are on different logical devices (file sys- 
tems). 
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AUTHOR 

rename ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

open(2). 

STANDARDS CONFORMANCE 

rename ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

rmdir - remove a directory file 

SYNOPSIS 

int rmdir (const char *path) ; 

DESCRIPTION 

rmdir () 

files . and . . ) before it can be removed. 

RETURN VALUE 

rmdir ( ) returns if the directory removal succeeds; otherwise, it returns -1 and sets errno to indicate 
the error. 

ERRORS 

rmdir ( ) fails and the directory is not removed if any of the following conditions are encountered: 



The directory must oe empty ^except i r 



[EACCES] 

[EACCESJ 

[EBUSY] 

[EEXIST] 

[EFAULT] 

[EINVAL] 

[ELOOP] 

[ENAMETOOLONG] 

[ENOENT] 
[ENOTDIR] 
[EPERM] 

[EROFS] 



A component of the path prefix denies search permission. 

Write permission is denied on the directory containing the link to be removed. 

The directory to be removed is the mount point for a mounted file system. 

The named directory is not empty. It contains files other than . and . . . 

path points outside the process's allocated address space. The reliable detection 
of this error is implementation dependent. 

The path is . . 

Too many symbolic links were encountered in translating the path name. 

The length of the specified path name exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

The named file does not exist. 

A component of the path is not a directory. 

The directory containing the directory to be removed has the sticky bit set and 
neither the containing directory nor the directory to be removed are owned by 
the effective user ID. 

The directory entry to be removed resides on a read-only file system. 



AUTHOR 

rmdir ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

mkdir(2), unlink(2). 

STANDARDS CONFORMANCE 

rmdir ( ) : AES, SVID2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

rtprio - change or read real-time priority 

SYNOPSIS 

ttinclude <sys/rtprio.h> 

int rtprio (pid_t pid, int prio) ; 

DESCRIPTION 

rtprio ( ) is used to set or read the real-time priority of a process. lipid is zero, it names the calling pro- 
cess: otherwise it gives the pid of the process. When setting the real-time priority of another process, the 
real or effective user ID of the calling process must match the real or saved user ID of the process to be 
modified, or the effective user ID of the calling process must be that of a user having appropriate privileges. 
The calling process must also be a member of a privilege group allowing rtprio ( ) (see getprivgrp(2)) or 
the effective user ID of the calling process must be a user having appropriate privileges. Simply reading 
real-time priorities requires no special privilege. 

Real-time scheduling policies differ from normal timesharing policies in that the real-time priority is used 
to absolutely order all real-time processes; this priority is not degraded over time. All real-time processes 
are of higher priority than normal user and system processes, although some system processes may run at 
real-time priorities. If there are several eligible processes at the same priority level, they are run in a round 
robin fashion as long as no process with higher priority intervenes. A real-time process receives CPU service 
until it either voluntarily gives up the CPU or is preempted by a process of equal or higher priority. Inter- 
rupts can also preempt a real-time process. 

Valid real-time priorities run from zero to 127. Zero is the highest (most important) priority. This real-time 
priority is inherited across fork ( ) s and exec ( ) s. 

prio specifies the following: 

0-127 Set process to this real-time priority. 

RTPRIO_NOCHG Do not change real-time priority. This is used for reading the process real-time 
priority. 

RTPRIO_RTOFF Set this process to no longer have a real-time priority. It resumes a normal 
timesharing priority. Any process, regardless of privilege, is allowed to turn off 
its own real-time priority using a pid of zero. 

EXAMPLES 

The following call to rtprio ( ) sets the calling process to a real-time priority of 90: 

rtprio (0, 90); 

RETURN VALUE 

If no error occurs, rtprio ( ) returns the pid's former (before the call) real-time priority. If the process 
was not a real-time process, RTPRIO_RTOPP is returned. If an error occurs, rtprio ( ) returns -1 and 
sets errno to indicate the error. 

ERRORS 

rtprio ( ) fails if any of the following conditions are encountered: 

[EINVAL] prio is not RTPRIO_NOCHG, RTPRIO_RTOFF, or in the range of through 127. 

[EPERM] The calling process is not a user having appropriate privileges, and neither its 

real or effective user-id match the real or saved user ID of the process indicated 
by pid. 

[EPERM] The group access list of the calling process does not contain a group having 

PRIV_RTPRIO capability and prio is not RTPRIO_NOCHG, or 
RTPRIO_RTOFF with a. pid of zero. 

[ESRCH] No process can be found corresponding to that specified by pid. 

DEPENDENCIES 
Series 800: 

Because processes executing at real-time priorities get scheduling preference over a system process execut- 
ing at a lower priority, unexpected system behavior can occur after a power failure on systems that support 
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power-fail recovery. For example, when init(lM) receives the powerfail signal SIGPWR, it normally reloads 
programmable hardware such as terminal multiplexers. If a higher-priority real-time process is eligible to 
run after the power failure, running of init is delayed. This condition temporarily prevents terminal 
input to any process, including real-time shells of higher priority than the eligible real-time process. To 
avoid this situation, a real-time process should catch SIGPWR and suspend itself until init has finished 
its powerfail processing. 

AUTHOR 

rtprio ( ) was developed by HP. 

SEE ALSO 

rtprio(l), getprivgrp(2), nice(2), plock(2), privilege(5). 

WARNINGS 

Normally, compute-bound programs should not be run at real-time priorities, because all time sharing work 
on the CPU would come to a complete halt. 
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NAME 

select - synchronous I/O multiplexing 

SYNOPSIS 

ttinclude <time.h> 

int select ( 

size_t nfds, 

int *readfds, 

int *writefds, 

int *exceptfds, 

const struct timeval * timeout 
); 

DESCRIPTION 

select ( ) examines the file descriptors specified by the bit masks readfds, writefds, and exceptfds. The 
bits from through nfds-1 are examined. File descriptor f is represented by the bit l«f in the masks. 
More formally, a file descriptor is represented by: 

fds[(f / BITS_PER_INT)] & (1 « (f % BITS_PER_INT)) 

When select ( ) completes successfully it returns the three bit masks modified as follows: For each file 
descriptor less than nfds, the corresponding bit in each mask is set if the bit was set upon entry and the file 
descriptor is ready for reading or writing, or has an exceptional condition pending. 

If timeout is a non-zero pointer, it specifies a maximum interval to wait for the selection to complete. If 
timeout is a zero pointer, the select waits until an event causes one of the masks to be returned with a valid 
(non-zero) value. To poll, the timeout argument should be non-zero, pointing to a zero valued timeval struc- 
ture. Specific implementations may place limitations on the maximum timeout interval supported. The 
constant MAX_ALARM defined in <sys/param.h> specifies the implementation-specific maximum (in 
seconds). Whenever timeout specifies a value greater than this maximum, it is silently rounded down to 
this maximum. On all implementations, MAX_ALARM is guaranteed to be at least 31 days (in seconds). 
Note that the use of a timeout does not affect any pending timers set up by alarm ( ) or set it imer ( ) 
(see alarm{2) or setitimer(2)). 

Any or all of readfds, writefds, and exceptfds can be given as if no descriptors are of interest. If all the 
masks are given as and timeout is not a zero pointer, select ( ) blocks for the time specified, or until 
interrupted by a signal. If all the masks are given as and timeout is a zero pointer, select ( ) blocks 
until interrupted by a signal. 

Ordinary files always select true whenever selecting on reads, writes, and/or exceptions. 

EXAMPLES 

The following call to select ( ) checks if any of 4 terminals are ready for reading, select ( ) times out 
after 5 seconds if no terminals are ready for reading. Note that the code for opening the terminals or read- 
ing from the terminals is not shown in this example. Also, note that this example must be modified if the 
calling process has more than 32 file descriptors open. Following this first example is an example of select 
with more than 32 file descriptors. 

ttdefine MASK(f) (1 « (f)) 
ttdefine NTTYS 4 

int tty [NTTYS]; 

int ttymask [NTTYS] ; 

int readmask =0; 

int readfds ; 

int nfound, i; 

struct timeval timeout; 

/* First open each terminal for reading and put the 

* file descriptors into array tty [NTTYS] . The code 

* for opening the terminals is not shown here. 
*/ 

for (i=0; i < NTTYS; i++) { 
ttymask[i] = MASK (tty [i] ) ; 
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readmask |= ttymaskfi]; 
} 

timeout. tv_sec =5; 
timeout .tv_usec = 0; 
readfds = readmask; 

/* select on NTTYS+3 file descriptors if stdin, stdout 
* and stderr are also open 
*/ 
if ( (nf ound = select (NTTYS+3, fcreadfds, 0, 0, &timeout) ) == -1) 

perror ("select failed"); 
else if (nfound == 0) 

printf ("select timed out \n" ); 
else for (1=0; i < NTTYS; i++) 
if (ttymaskfi] & readfds) 

/* Read from tty[i] . The code for reading 
* is not shown here. 
*/ 
else printf ("tty[%d] is not ready for reading \n",i); 

The following example is the same as the previous example, except that it works for more than 32 open 
files. Definitions for howmany, f d_set, and NPDBITS are in <sys/types . h>. 

#include <sys/param.h> 
ftinclude <sys/types.h> 
#include <sys/time.h> 

ttdefine MASK(f) (1 « (f)) 

ttdefine NTTYS NOPILE - 3 

#define NWORDS howmany (FD_SETSIZE, NPDBITS) 

int tty [NTTYS] ; 

int ttymask [NTTYS] ; 

struct fd_set readmask, readfds; 

int nfound, i, j, k; 

struct timeval timeout; 

/* First open each terminal for reading and put the 

* file descriptors into array tty [NTTYS] . The code 

* for opening the terminals is not shown here. 
*/ 

for (k=0; k < NWORDS; k++) 
readmask. f ds_bit s [k] =0; 

for (1=0, k=0; 1 < NTTYS && k < NWORDS; k++) 

for (j=0; j < NPDBITS && i < NTTYS; j++, 1++) { 
ttymask[i] = MASK(tty [i] ) ; 
readmask. fds_bits [k] |= ttymaskfi]; 
} 

timeout .tv_sec =5; 
t imeout . tv__usec = ; 
for (k=0; k < NWORDS; k++) 

readfds. fds_bits [k] = readmask. fds_bits[k] ; 

/* select on NTTYS+3 file descriptors if stdin, stdout 

* and stderr are also open 
*/ 

if ((nfound = select (NTTYS+3, fcreadfds, 0, 0, fctimeout)) == -1) 

perror ("select failed"); 
else if (nfound == 0) 

printf ("select timed out \n"); 
else for (i=0, k=0; i < NTTYS && k < NWORDS; k++) 
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for (j=0; j < NFDBITS && i < NTTYS; j + + , i++) 
if (ttymaskti] & readfds.fds_bits [k] ) 

/* Read from tty[i]. The code for reading 
* is not shown here. 
*/ 
else printf ("tty[%d] is not ready for reading \n",i); 

RETURN VALUE 

select ( ) returns the number of descriptors contained in the bit masks, or -1 if an error occurred. If the 
time limit expires, select ( ) returns and all the masks are cleared. 

ERRORS 

select ( ) fails if any of the following conditions are encountered: 

[EBADF] One or more of the bit masks specified an in valid descriptor. 

[EINTR] A signal was delivered before any of the selected for events occurred or before the 

time limit expired. 

DEFAULT] One or more of the pointers was invalid. The reliable detection of this error is imple- 

mentation dependent. 

[EINVAL] Invalid timeval passed for timeout. 

[EINVAL] The value of nfds is less than zero. 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can 
affect the behavior described on this page. 

The file descriptor masks are always modified on return, even if the call returns as the result of a timeout. 

DEPENDENCIES 

Series 300/400 

select ( ) supports the following devices and file types: 

• pipes 

• fifo special files (named pipes) 

• All serial interfaces 

• All ITEs (internal terminal emulators) and HP-HIL input devices 

• pty(l) special files 

• sockets 

• HP 98643 LAN interface card driver 

File types not supporting select ( ) always return true. 

Series 700/800 

select ( ) supports the following devices and file types: 

pipes 

fifo special files (named pipes) 

all serial devices 

All ITEs (internal terminal emulators) and HP-HIL input devices 

hpib(7) special files 

gpio(7) special files (Series 800 Only for Release 8.0) 

lan{l) special files 

pty(7) special files 

sockets 

The convention for device files that do not support select ( ) is to always return true for those condi- 
tions the user is selecting on. 

Consult individual device manual entries to determine the extent to which any particular driver sup- 
ports select. 

HP Clustered Environment 

In a clustered environment, select () is not supported for distributed fifos; i.e., fifos that are 
open simultaneously on multiple machines. In this case an error of EINVAL is returned. 
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AUTHOR 

select ( ) was developed by HP and the University of California, Berkeley. 

SEE ALSO 

fcntl(2), read(2), write(2). 
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NAME 

semctl - semaphore control operations 

SYNOPSIS 

ttinclude <sys/sem.h> 

int semctl (int semid, 
int semnum, 
int cmd, . . . 
/* arg */ 
) ; 

DESCRIPTION 

semctl ( ) provides a variety of semaphore control operations as specified by cmd. 

The following cmds are executed with respect to the semaphore specified by semid and semnum : 

GETVAL Return the value of semval (see semaphore identifier in glossary (9)). Requires Read 

permission. 

SETVAL Set the value of semval to arg, where arg is the fourth argument of semctl () 

taken as an int. When this cmd is successfully executed, the semadj value 
corresponding to the specified semaphore in all processes is cleared. Requires Alter 
permission. 

GETPID Return the value of sempid. Requires Read permission. 

GETNCNT Return the value of semncnt. Requires Read permission. 

GETZCNT Return the value of semzcnt. Requires Read permission. 

The following cmds return and set, respectively, every semval in the set of semaphores. 

GETALL Place semvals into array pointed to by arg, where arg is the fourth argument of 

semctl () taken as a pointer to unsigned short int. Requires Read per- 
mission. 

SETALL Set semvals according to the array pointed to by arg, where arg is the fourth argu- 

ment of semctl () taken as a pointer to unsigned short int. When this 
cmd is successfully executed, the semadj values corresponding to each specified 
semaphore in all processes are cleared. Requires Alter permission. 

The following cmds are also available: 

IPC_STAT Place the current value of each member of the data structure associated with semid 
into the structure pointed to by arg, where arg is the fourth argument of 
semctl ( ) taken as a pointer to struct semid_ds. The contents of this struc- 
ture are defined in glossary (9). Requires Read permission. 

IPC_SET Set the value of the following members of the data structure associated with semid 

to the corresponding value found in the structure pointed to by arg, where arg is 
the fourth argument of semctl ( ) taken as a pointer to struct semid_ds: 

sem_perm.uid 
sem_perm.gid 
sem_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an effective user ID equal to either that of super- 
user or to the value of either sem_perm . uid or sem_perm . cuid in the data structure associated 
with semid. 

IPC_RMID 

Remove the semaphore identifier specified by semid from the system and destroy the set of sema- 
phores and data structure associated with it. This cmd can only be executed by a process that has an 
effective user ID equal to either that of super-user or to the value of either sem_perm.uid or 
sem_perm . cuid in the data structure associated with semid. 

EXAMPLES 

The following call to semctl ( ) initializes the set of 4 semaphores to the values 0, 1, 0, and 1 respectively. 
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This example assumes the process has a valid semid representing a set of 4 semaphores as shown in the 
semget(2) manual entry. For an example of performing "P" and "V" operations on the semaphores below, 
refer to semop(2). 

ushort semarray[4] ; 

semarray [ ] = ; 

semarray[l] =1; 

semarray [2] = 0; 

semarray [3] = 1; 

semctl (mysemid, 0, SETALL, semarray); 

RETURN VALUE 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETNCNT The value of semncnt. 

GETZCNT The value of semzcnt. 

GETP ID The value of sempid. 

All others return a value of 0. 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

semctl ( ) fails if any of the following conditions are encountered: 

[EACCES] Operation permission is denied to the calling process (see semaphore operation per- 

missions in glossary (9). 

[EFAULT] cmd is equal to GETVAL, SETVAL, GETALL, SETALL, IPC_STAT, or IPC_SET, 

andarg. 

[EINVAL] semid is not a valid semaphore identifier. 

[EINVAL] semnum is less than zero or greater than or equal sem_nsems. 

[EINVAL] cmd is not a valid command. 

[EPERM] cmd is equal to IPC_RMIDor IPC_SET and the effective user ID of the calling pro- 

cess is not equal to that of super-user and it is not equal to the value of either 
sem perm ,u id or sem perm . cuid in the data structure associated with semid. 

[ERANGE] cmd is SETVAL or SETALL and the value to which semval is to be set is greater 

than the system imposed maximum. 

SEE ALSO 

ipcrm(l), ipcs(l), semget(2), semop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

semctl ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

semget - get set of semaphores 

SYNOPSIS 

#include <sys/sem.h> 

int semget (key_t key, int nsems, lnt semf lg) ; 

DESCRIPTION 

semget ( ) returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set containing nsems semaphores are created for 
key if one of the following is true: 

key is equal to IPC_PRIVATE. This call creates a new identifier, subject to available resources. The 
identifier is never returned by another call to semget ( ) until it has been released by a call to 
semctl ( ) . The identifier should be used among the calling process and its descendents; however, it 
is not a requirement. The resource can be accessed by any process having the proper permissions. 

key does not already have a semaphore identifier associated with it, and (semflg & IPC_CREAT) is 
"true". 

Specific behavior can be requested by ORing the following masks into semflg. 

IPC_CREAT: Create a semaphore identifier if one does not already exist for key. 

IPC_EXCL: If IPC_CREAT is specified and key already has a semaphore identifier associated with 
it, return an error. 

The low-order 9 bits of semflg are the semaphore operation permissions which are defined ia glossary (9). 

Upon creation, the data structure associated with the new semaphore identifier is initialized as follows: 

In the operation-permission structure, sem_perm. cuid and sem pentuuid are set equal to the 
effective-user-ID of the calling process, while sem perm.cqld and sem_perm. gid are set to the 
effective-group-ID of the calling process. 

The low-order 9 bits of sem_perm .mode are set equal to the low -order 9 bits of semflg. 

sem_nsems is set equal to the value of nsems. 

sem_ot ime is set equal to and sem_ct ime is set equal to the current time. 

EXAMPLES 

The following call to semget () returns a semid associated with the key returned by ftok("myfile", 
'A' ) . If a semid associated with the key does not exist, a new semid, set of 4 semaphores, and associated 
data structure will be created. If a semid for the key already exists, the semid is simply returned. 

int semid; 

mysemid = semget (f tok("myf ile", 'A' ) , 4, IPC_CREAT I 0600); 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a semaphore identifier, is returned. Otherwise, 
a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

semget ( ) fails if one or more of the following is true: 

[EINVAL] nsems is either less than or equal to zero or greater than the system-imposed limit. 

[EACCES] A semaphore identifier exists for key, but operation permission as specified by the 

low-order 9 bits of semflg would not be granted. 

[EINVAL] A semaphore identifier exists for key , but the number of semaphores in the set associ- 

ated with it is less than nsems, and nsems is not equal to zero. 

[ENOENT] A semaphore identifier does not exist for key and {semflg & IPC_CREAT) is "false". 

[ENOSPC] A semaphore identifier is to be created, but the system-imposed limit on the max- 

imum number of allowed semaphore identifiers system wide would be exceeded. 
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[EEXIST] A semaphore identifier exists for key but ( {semflgSc IPC_CREAT) && {semflg & 

IPC_EXCL)) is "true". 

SEE ALSO 

ipcrm(l), ipcs(l), semctl(2), semop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

semget ( ) : SVID2, XPC-2, XPG-3, XPG4 



I 
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NAME 

semop - semaphore operations 

SYNOPSIS 

#include <sys/sem.h> 

int semop ( 

int semid, 

struct sembuf *sops, 

unsigned int nsops 
); 

DESCRIPTION 

semop ( ) is used to atomically perform an array of semaphore operations on the set of semaphores associ- 
ated with the semaphore identifier specified by semid. sops is a pointer to the array of semaphore-operation 
structures, nsops is the number of such structures in the array. The contents of each structure includes the 
following members: 

semaphore number */ 
semaphore operation */ 
operation flags */ 

Each semaphore operation specified by sem_op is performed on the corresponding semaphore specified by 
semid and semjium. Semaphore array operations are atomic in that none of the semaphore operations are 
performed until blocking conditions on all of the semaphores in the array have been removed. 

semjop specifies one of three semaphore operations as follows: 

If semjop is a negative integer, one of the following occurs: 

If semval (see semaphore identifier in glossary(9)) is greater than or equal to the absolute value 
of semjop, the absolute value of semjop is subtracted from semval. Also, if (semjlg & 
SEM_UNDO) is 'true", the absolute value of semjop is added to the calling process's semadj value 
(see glossary(9) and exit(2)) for the specified semaphore. 

If semval is less than the absolute value of semjop and (semjlg & IPC_NOWAIT) is "true", 
semop () returns immediately. 

If semval is less than the absolute value of semjop and {semjlg & IPC_NOWAIT) is "false", 
semop ( ) increments the semncnt associated with the specified semaphore and suspend execu- 
tion of the calling process until one of the following conditions occur: 

semval becomes greater than or equal to the absolute value of semjop. When this occurs, I 

the value of semncnt associated with the specified semaphore is decremented, the absolute ™ 

value of semjop is subtracted from semval and, if {semjlg & SEM_UNDO) is "true", the 
absolute value of semjop is added to the calling process's semadj value for the specified 
semaphore. 

The semid for which the calling process is awaiting action is removed from the system (see 
semctl(2)). When this occurs, errno is set equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. When this occurs, the value of 
semncnt associated with the specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal(5). 

If semjop is a positive integer, the value of semjop is added to semval and, if (semjlg & SEMJDNDO) is 
"true", the value of semjop is subtracted from the calling process's semadj value for the specified sema- 
phore. 

If semjop is zero, one of the following occurs: 

If semval is zero, semop ( ) proceeds to the next semaphore operation specified by sops, or returns 
immediately if this is the last operation. 

If semval is not equal to zero and (semjlg & IPC_NOWAIT) is "true", semop ( ) returns immedi- 
ately. 
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If semval is not equal to zero and {semjlg & IPC_NOWAIT) is "false", semop() increments the 
semzcnt associated with the specified semaphore and suspends execution of the calling process until 
one of the following occurs: 

semval becomes zero, at which time the value of semzcnt associated with the specified sema- 
phore is decremented. 

The semid for which the calling process is awaiting action is removed from the system. When 
this occurs, errno is set equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. When this occurs, the value of 
semzcnt associated with the specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal(5). 

EXAMPLES 

The following call to semop ( ) atomically performs a "P" or "get" operation on the second semaphore in the 
semaphore set and a "V" or "release" operation on the third semaphore in the set. This example assumes 
the process has a valid semid which represents a set of 4 semaphores as shown on the semget(2) manual 
page. It also assumes that the semvals of the semaphores in the set have been initialized as shown in the 
semctl(2) manual entry. 

struct sembuf sops [4]; 

sops [0] . sem_num =1; 

sops [ ] . sem_op = - 1 ; /* P (get) */ 

sops [0] .sem_flg = 0; 

sops [1 ] . sem_num = 2 ; 

sops [ 1 ] . sem_op = 1 ; /* V (release) */ 

sops [1] .sem_f lg = 0; 

semop (mysemid, sops, 2); 

RETURN VALUE 

If semop ( ) returns due to the receipt of a signal, a value of -1 is returned to the calling process and 
errno is set to EINTR. If it returns due to the removal of a semid from the system, a value of -1 is returned 
and errno is set to EIDRM. 

Upon successful completion, a non-negative value is returned. Otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

semop ( ) fails if one or more of the following is true for any of the semaphore operations specified by sops: 

[EINVAL] semid is not a valid semaphore identifier. 

[EFBIG] semjium is less than zero or greater than or equal to the number of semaphores in 

the set associated with semid. 

[E2BIG] nsops is greater than the system-imposed maximum. 

[EACCES] Operation permission is denied to the calling process (see glossary (9)). 

[EAGAIN] The operation would result in suspension of the calling process but (semjlg & 

IPC_NOWAIT) is "true". 

[ENOSPC] The limit on the number of individual processes requesting an SEM_UNDO would be 

exceeded. 

[EINVAL] The number of individual semaphores for which the calling process requests a 

SEM_DNDO would exceed the limit. 

[ERANGE] An operation would cause a semval to overflow the system-imposed limit. 

[ERANGE] An operation would cause a semadj value to overflow the system-imposed limit. 

[EFAULT] sops points to an illegal address. The reliable detection of this error will be imple- 

mentation dependent. 

Upon successful completion, the value of sempid for each semaphore specified in the array pointed to 
by sops is set equal to the process ID of the calling process. The value of sem_otlme in the data 
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structure associated with the semaphore identifier will be set to the current time. 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can 
affect the behavior described on this page. 

SEE ALSO 

ipcs(l), exec(2), exit(2), fork(2), semctl(2), semget(2), stdipc(3C), signal(5). 

STANDARDS CONFORMANCE 

semop ( ) : SVID2, XPG2, XPG3, XPG4 



I 
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NAME 

send, sendto, sendmsg - send a message from a socket 

SYNOPSIS 

#include < sys/ socket .h> 

int send(int s, const void *msg, int len, int flags); 

int sendto ( 
int s, 

const void *msg / 
int len, 
int flags, 
const void *to, 
int tolen) ; 

int sendmsg(int s, const struct msghdr msg[], int flags); 

DESCRIPTION 

send ( ) , sendto ( ) , and sendmsg ( ) are used to transmit a message to another socket, send ( ) can 
be used only when the socket is in a connected state, whereas sendto ( ) and sendmsg ( ) can be used 
at any time, sendmsg () allows the send data to be gathered from several buffers specified in the 
msghdr structure. See recv (2) for a description of the msghdr structure. 

s is a socket descriptor that specifies the socket on which the message will be sent, msg points to the buffer 
containing the message. 

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be 
used after the connection has been established (see connect(2)). In this case, any destination specified by to 
is ignored. For connectionless sockets, such as SOCK_DGRAM, sendto ( ) must be used unless the destina- 
tion address has already been specified by connect ( ) . If the destination address has been specified and 
sendto ( ) is used, an error results if any address is specified by to. 

The address of the target is contained in a socket address structure pointed at by to, with tolen specifying 
the size of the structure. 

If a sendto ( ) is attempted on a SOCKJ3GRAM socket before any local address has been bound to it, the 
system automatically selects a local address to be used for the message. In this case, there is no guarantee 
that the same local address will be used for successive sendto ( ) requests on the same socket. 

The length of the message is given by len, in bytes. The length of data actually sent is returned. If the 
message is too long to pass atomically through the underlying protocol, the message is not transmitted, -1 is 
returned, and errno is set to EMSGSIZE. For SOCKJDGRAM sockets, this size is fixed by the implementa- 
tion (see the DEPENDENCIES section below). Otherwise there is no size limit. 

No indication of failure to deliver is implicit in a send/sendto. Return values of -1 indicate some locally- 
detected errors. 

If no buffer space is available to hold the data to be transmitted, send ( ) blocks unless non-blocking mode 
is enabled. There are three ways to enable non-blocking mode: 

• With the FIOSNBIO ioctl () request, 

• With the 0_NONBLOCK flag, and 

• With the C_NDELAY fcntl() flag. 

If non-blocking I/O is enabled using FIOSNBIO or the equivalent FIONBIO request (defined in 
<sys/ioctl.h> and explained in ioctl(2) ioctl(5\ and socket(7)\ although use of FIONBIO is not 
recommended, the send ( ) request completes in one of three ways: 

• If there is enough space available in the system to buffer all the data, send ( ) completes suc- 
cessfully, having written out all of the data, and returns the number of bytes written. 

• If there is not enough space in the buffer to write out the entire request, send() completes 
successfully, having written as much data as possible, and returns the number of bytes it was 
able to write. 
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• If there is no space in the system to buffer any of the data, send ( ) fails, having written no 
data, and err no is set to EWOULDBLOCK. 

If non-blocking I/O is disabled using PIOSNBIO, send() always executes completely (blocking as 
necessary) and returns the number of bytes written. 

If the 0_NONBLOCK flag is set using fcntl() (defined in <sys/f cntl.h> and explained in fcntl(2) 
and fcntl(5)), POSIX-style non-blocking I/O is enabled. In this case, the send ( ) request completes in 
one of three ways: 

• If there is enough space available in the system to buffer all the data, send ( ) completes suc- 
cessfully, having written out all of the data, and returns the number of bytes written. 

• If there is not enough space in the buffer to write out the entire request, send ( ) completes 
successfully, having written as much data as possible, and returns the number of bytes it was 
able to write. 

• If there is no space in the system to buffer any of the data, send ( ) completes, having written 
no data, and returns -1, with errno set to EAGAIN. 

If the 0_NDELAY flag is set using f cntl ( ) (denned in <sys/f cnt 1 . h> and explained in fcntl(2) 
and fcntl (5)), non-blocking I/O is enabled. In this case, the send() request completes in one of three 
ways: 

• If there is enough space available in the system to buffer all the data, send ( ) completes suc- 
cessfully, having written out all of the data, and returns the number of bytes written. 

• If there is not enough space in the buffer to write out the entire request, send ( ) completes 
successfully, having written as much data as possible, and returns the number of bytes it was 
able to write. 

• If there is no space in the system to buffer any of the data, send() completes successfully, 
having written no data, and returns 0. 

If the 0_NDELAY flag is cleared using fcntl (), non-blocking I/O is disabled. In this case, the 
send ( ) always executes completely (blocking as necessary) and returns the number of bytes written. 

Since both the fcntl () 0_NONBLOCK and 0_NDE LAY flags and PIOSNBIO ioctl() request are 
supported, some clarification on how these features interact is necessary. If the 0_NONBLOCK or 
0_NDELAY flag has been set, send ( ) requests behave accordingly, regardless of any PIOSNBIO 
requests. If neither the 0_NONBLOCK nor 0_NDE LAY flag has been set, FIOSNBIO requests con- 
trol the behavior of send ( ) . If the 0_NDELAY flag has not been set, FIOSNBIO requests control the 
behavior of send ( ) . 

The default is that non-blocking I/O is not enabled. 

The supported values for flags are zero, or MSG_OOB (to send out-of-band data). A write ( ) call made 
to a socket behaves in exactly the same way as send ( ) with flags set to zero. MSG_OOB is not sup- 
ported for AF_UNIX sockets. 

The select{2) call can be used to determine when it is possible to send more data. 

AF_CCITT only: 

Sockets of the address family AF_CCITT operate in message mode. Although they are specified as 
connection-based (SOCK_STREAM) sockets, the X.25 subsystem communicates via messages. They require 
that a connection be established with the connect ( ) or accept ( ) calls. 

The 0_NDELAY flag is not supported, use PIOSNBIO requests to control non-blocking I/O. If the avail- 
able buffer space is not large enough for the entire message, and the socket is in non-blocking mode, the 
error EWOULDBLOCK is returned. If the amount of data in the send ( ) exceeds the maximum outbound 
message size, EMSGSIZE is returned. 

The sendto() call is not supported. 

Each call sends either a complete or a partial X.25 message. This is controlled by the setting of More-Data- 
To-Follow (MDTF) bit. If the user wants to send a partial message, MDTF should be set to 1 before the 
send ( ) call. The MDTF bit should be cleared to before sending the final message fragment. 
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Message fragment length may range from bytes up to the size of the socket's send buffer (see af_ccitt(7F)). 
The MDTF bit and multiple send( ) calls can be combined to transmit complete X.25 packet sequences 
(i.e., zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in which the 
More Data bit is clear) of arbitrary length. Note that a 0-byte message is not actually sent, but may be 
necessary to flush a complete X.25 message if the user is controlling the MDTF bit. 

Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as INTERRUPT Data 
packet in X.25 terminology), or up to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recom- 
mendations. INTERRUPT data packets sent in blocking mode cause the process to block until confirmation 
is received. INTERRUPT data packets sent with the socket in non-blocking mode do not cause the process to 
block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is 
received (see recv(2)). 

DEPENDENCIES 

UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU 
varies for different link types. These pieces, called IP fragments, can be transmitted, but IP does not 
guarantee delivery. Sending large messages may cause so many fragments to be created that some of them 
overrun a receiver's ability to receive them, and hence are dropped. If this happens, even if most of the 
fragments ultimately arrive at the destination, the complete message cannot be re-assembled. This affects 
the apparent reliability and throughput of the network, as viewed by the end-user. 

Default and maximum buffer sizes are protocol-specific. Refer to the appropriate entries in Sections 7F 
and 7P for details. The buffer size can be set by calling setsockopt ( ) with SO_SNDBUP. 

AFCCITT 

If the receiving process is on a Series 700/800 HP-UX system and the connection has been set up to use the 
D-bit, data sent with the D-bit set is acknowledged when the receiving process has read the data. Other- 
wise, the acknowledgement is sent when the firmware receives it. 

If the receiving process is on a Series 300/400 HP-UX system, data sent with the D-bit set is acknowledged 
when the data reaches the X.25 interface card, but D-bit acknowledgement from a Series 300/400 does not 
imply that the receiving process has read the data. 

RETURN VALUE 

Upon successful completion, send(), sendto(), and sendmsgO return the number of bytes sent. 
Otherwise, they return -1 and set errno to indicate the error. 

DIAGNOSTICS 

send ( ) , sendto ( ) , and sendmsg ( ) fail if any of the following conditions are encountered: 

[EACCES] Process doing a send() of a broadcast packet does not have broadcast capa- 

bility enabled for the socket. Use setsockopt ( ) to enable broadcast capa- 
bility. 

[EBADF] An invalid descriptor was specified. 

[ENOTSOCK] The argument s is not a socket. 

[EFAULT] An invalid pointer was specified in the msg or to parameter, or in the msghdr 

structure. 

[EMSGSIZE] A length in the msghdr structure is invalid. The socket requires that mes- 

sages be sent atomically, and the size of the message to be sent made this 
impossible. SOCK_DGRAM/AF_INET and/or SOCK_STREAM/AF_CCITT Only: 
The message size exceeded the outbound buffer size. 

[EWOULDBLOCK] The socket is in non-blocking mode and the requested operation would block. 

[ENOBUFS] Insufficient network memory resources were available in the system to per- 

form the operation. 

[EINTR] The operation was interrupted by a signal before any data were sent. (If some 

data was sent, send() returns the number of bytes sent before the signal, 
and EINTR is not given.) 

[EINVAL] The len or tolen parameter, or a length in the msghdr structure is invalid. A 

sendto ( ) system call was issued on an X25 socket, or the connection is in 
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its reset sequence and cannot accept data. 

[EDESTADDRREQ] The to parameter needs to specify a destination address for the message. This 

is also given if the specified address contains unspecified fields (see inet{l¥)). 

[ENOTCONN] A send( ) on a socket that is not connected, or a send ( ) on a socket that 

has not completed the connect sequence with its peer, or is no longer con- 
nected to its peer. 

[EISCONN] An address was specified by to for a SOCKJDGRAM socket which is already con- 

nected. 

[EAFNOSUPPORT] Requested address does not match the address family of this socket. 

[EPIPE] and SIGPIPE signal 

An attempt was made to send on a socket that was connected, but the connec- 
tion has been shut down, either by the remote peer or by this side of the con- 
nection. Note that the default action for SIGPIPE, unless the process has 
established a signal handler for this signal, is to terminate the process. 



[EIO] 
[ENETDOWN] 

[EOPNOTSUPP] 

[ENETUNREACH] 



A timeout occurred. 

The interface used for the specified address is "down" (see ifconfigOM)), or no 
interface for the specified address can be found, (SO_DONTROUTE socket 
option in use), or the X.25 Level 2 is down. 

The MSG_OOB flag was specified; it is not supported for AF_UNIX sockets. 

(LAN) All encapsulations (e.g., ether, ieee) have been turned off (see also 
lanconfigiXM), and ifconfigilM)). 

(X.25) The X.25 Level 2 is down. The X.25 link layer is not working (wires 
might be broken, or connections are loose on the interface hoods at the 
modem, or the modem failed, or the packet switch at the remote end lost 
power or failed for some reason, or electrical noise interfered with the line for 
an extremely long period of time). 



[ECONNRESET] 



A connection was forcibly closed by a peer. 

AUTHOR 

send ( ) was developed at the University of California, Berkeley. 

SEE ALSO 

lanconfig(lM), ifconfig(lM), getsockopt(2), recv(2), select(2), setsockopt(2), socket(2), af_ccitt(7F), inet(7F), 
socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P). 
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NAME 

setacl, fsetacl - set access control list (ACL) information 

SYNOPSIS 

ttinclude <sys/acl.h> 

int setacl ( 

size_t nentries, 
const struct acl_entry *acl 
); 

int fsetacl ( 

int fildes, 

slze_t nentries, 

const struct acl_entry *acl 
); 

DESCRIPTION 

setacl ( ) sets an existing file's access control list (ACL) or deletes optional entries from it. path points to 
a path name of a file. 

Similarly, fsetacl ( ) sets an existing file's access control list for an open file known by the file descriptor 
fildes . 

The effective user ID of the process must match the owner of the file or be the super-user to set a file's ACL. 

A successful call to setacl ( ) deletes all of a file's previous optional ACL entries (see explanation below), 
if any. nentries indicates how many valid entries are defined in the acl parameter. If nentries is zero or 
greater, the new ACL is applied to the file. If any of the file's base entries (see below) is not mentioned in 
the new ACL, it is retained but its access mode is set to zero (no access). Hence, routine calls of setacl ( ) 
completely define the file's ACL. 

As a special case, if nentries is negative (that is, a value of ACL_DELOPT (defined in <sys/acl ,h>), the 
acl parameter is ignored, all of the file's optional entries, if any, are deleted, and its base entries are left 
unaltered. 

Some of the miscellaneous mode bits in the file's mode might be turned off as a consequence of calling 
setacl ( ) . See chmod(2). 

Access Control Lists 

An ACL consists of a series of entries. Entries can be categorized in four levels of specificity: 

(u .g, mode) applies to user u in group g 

{u.%, mode) applies to user u in any group 

(% .g, mode) applies to any user in group g 

(%.%, mode) applies to any user in any group 

Entries in the ACL must be unique; no two entries can have the same user ID (uid) and group ID (gid) (see 
below). Entries can appear in any order. The system orders them as needed for access checking. 

The <sys/acl .h> header file defines ACL_NSUSER as the non-specific uid value and ACLJNfSGROUP 
as the non-specific gid value represented by % above. If uid in an entry is ACL_NSUSER, it is a %.g entry. 
If gid in an entry is ACL_NS GROUP, it is a u .% entry. If both uid and gid are non-specific, the file's entry 
is%.%. 

The <unistd.h> header file defines meanings of mode bits in ACL entries (R_OK, W_OK, and X_OK). 
Irrelevant bits in mode values must be zero. 

Every file's ACL has three base entries which cannot be added or deleted, but only modified. The base ACL 
entries are mapped directly from the file's permission bits. 

(<file's owner> . ACL.NSGROUP, <file's owner mode bits>) 
(ACL_NSUSER . <file's group>, <file's group mode bits>) 
(ACL_NSUSER . ACL.NSGROUP, <file's other mode bits>) 

In addition, up to 13 optional ACL entries can be set to restrict or grant access to a file. 
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Altering a base ACL entry's modes with setacl ( ) changes the file's corresponding permission bits. The 
permission bits can be altered also by using chmod() (see chmod(2)) and read using stat() (see 
stat(2)). 

The number of entries allowed per file (see NACLENTRIES in <sys/acl .h>) is small for space and per- 
formance reasons. User groups should be created as needed for access control purposes. Since ordinary 
users cannot create groups, their ability to control file access with ACLs might be somewhat limited. 

RETURN VALUE 

Upon successful completion, setacl ( ) and f setacl ( ) return a value of zero. If an error occurs, they 
return -1, the file's ACL is not modified, and errno is set to indicate the error. 

ERRORS 

setacl () and fsetacl() fail if any of the following conditions are encountered: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist (for example, path is null or a component of path 

does not exist). 

[EBADF] fildes is not a valid file descriptor. 

[EACCES] A component of the path prefix denies search permission. 

[EPERM] The effective user ID does not match the owner of the file and the effective user 

ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path or act points outside the allocated address space of the process, or acl is not 

as large as indicated by nentries. 

[EINVAL] There is a redundant entry in the ACL, or acl contains an invalid uid, gid, or 

mode value. 

[E2BIG] An attempt was made to set an ACL with more than NACLENTRIES entries. 

[EOPNOTSUPP] setacl ( ) is not supported on remote files by some networking services. 

[ENOSPC] Not enough space on the file system. 

[ENFILE] System file table is full. 

[ENAMETOOLONG] The length of path exceeds PATH_MAX bytes, or the length of a component of 
path exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect. 

[ELOOP] Too many symbolic finks were encountered in translating the path name. 

[EDQUOT] User's disk quota block or inode limit has been reached for this file system. 

EXAMPLES 

The following code fragment defines and sets an ACL on file . . /shared which allows the file's owner to 
read, write, and execute or search the file, and allows user 103, group 204 to read the file. 

#include <unlstd.h> 
#include <sys/stat .h> 
#lnclude <sys/acl.h> 

char *fllename = "../shared"; 
struct acl_entry acl [2] ; 
struct stat statbuf; 

if (stat (filename, & statbuf) < 
error (...); 

acl [0] . uid = statbuf . st_uid; /* file owner */ 

acl [0] . gid = ACL_NSGROUP ; 

acl [0] . mode = R_OK | W_OK I X_OK; 

acl [1] . uid = 103; 
acl [1] . gid = 204; 
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acl [1] . mode = R_OK; 

if (setacl (filename, 2, acl)) 
error (...); 

The following call deletes all optional ACL entries from f ilel: 

setacl ("filel", ACL_DELOPT, (struct acl_entry *) 0) ; 

DEPENDENCIES 

NFS 

setacl ( ) and f setacl ( ) are not supported on remote files. 

AUTHOR 

setacl ( ) and f setacl ( ) were developed by HP. 

SEE ALSO 

access(2), chmod(2), getaccess(2), getacl(2), stat(2), acl(5), unistd(5). 
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NAME 

setaudid - set the audit ID (aid) for the current process 

SYNOPSIS 

#include <sys/audit .h> 

int setaudid (aid_t audid); 

DESCRIPTION 

setaudid ( ) sets the audit ID (aid) for the current process. This call is restricted to the super-user. 

RETURN VALUE 

Upon successful completion, setaudid ( ) returns a value of 0; otherwise, it returns -1 and sets errno 
to indicate the error. 

ERRORS 

setaudid ( ) fails if any of the following conditions are encountered: 

[EPERM] The caller is not a superuser. 

[EINVAL] The audit ID (audid) is invalid. 

AUTHOR 

setaudid ( ) was developed by HP. 

SEE ALSO 

getaudid(2). 
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NAME 

setaudproc - controls process level auditing for the current process and its decendents 

SYNOPSIS 

#include <sys/audit.h> 

int setaudproc ( int af lag) ; 

DESCRIPTION 

setaudproc ( ) controls process level auditing for the current process and its decendents. It accomplishes 
this by setting or clearing the u_audproc flag in the u area of the calling process. When this flag is set, 
the system audits the process; when it is cleared, the process is not audited. This call is restricted to super- 
users. 

One of the following aflags must be used: 

AUD_PROC Audit the calling process and its decendents. 
AUD_CLEAR Do not audit the calling process and its decendents. 

The u_audproc flag is inherited by the descendents of a process, consequently, the effect of a call to 
setaudproc ( ) is not limited to the current process, but propagates to all its decendents as well. For 
example, if setaudproc ( ) is called with the AUD_PROC flag, all subsequent audited system calls in the 
current process and its decendents are audited until setaudproc () is called with the AUD_CLEAR flag. 

Further, setaudproc ( ) performs its action regardless of whether the user executing the process has 
been selected to be audited or not. For example, if setaudproc ( ) is called with the AUD_PROC (or the 
AUD_CLEAR) flag, all subsequent audited system calls will be audited (or not audited), regardless of 
whether the user executing the process has been selected for auditing or not. 

Due to these features, setaudproc ( ) should not be used in most self-auditing applications, 
audswitch ( ) should be used (see audswitch{2)) when the objective is to suspend auditing within a pro- 
cess without affecting its decendents or overriding the user selection aspect of the auditing system. 

RETURN VALUE 

Upon successful completion, setaudproc ( ) returns 0; otherwise, it returns -1 and sets errno to indi- 
cate the error. 

AUTHOR 

setaudproc ( ) was developed by HP. 

SEE ALSO 

getaudproc(2), audswitch(2), audusr(lM), audevent(lM), audit(5). 
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NAME 

setevent - set current events and system calls which are to be audited 

SYNOPSIS 

#include < sys/ audit .h> 

int setevent ( 

const struct aud_type a_syscall[], 

const struct aud_event_tbl a_event[] 
); 

DESCRIPTION 

setevent ( ) sets the events and system calls to be audited. The event and system call settings in the 
tables pointed to by a_syscall and a_event become the current settings. This call is restricted to the super- 
user. 

RETURN VALUE 

Upon successful completion, setevent ( ) returns 0; otherwise, it returns -1 and sets errno to indicate 
the error. 

ERRORS 

setevent ( ) fails if the following condition is encountered: 

[EPERM] The caller is not super-user. 

AUTHOR 

setevent ( ) was developed by HP. 

SEE ALSO 

getevent(2), audevent(lM). 
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NAME 

setgroups - set group access list 

SYNOPSIS 

#include <unistd.h> 

int setgroups ( int ngroups, const gid_t *gidset); 

DESCRIPTION 

setgroups ( ) sets the group access list of the current user process according to the array gidset. The 
parameter ngroups indicates the number of entries in the array and must be no more than NGROUPS, as 
defined in <sys/param.h>. 

Only super-user can set new groups by adding to the group access list of the current user process; any user 
can delete groups from it. 

RETURN VALUE 

Upon successful completion, setgroups ( ) returns 0; otherwise it returns -1 and sets errno to indicate 
the error. 

ERRORS 

setgroups ( ) fails if any of the following conditions are encountered: 

[EPERM] The caller is not super-user and has attempted to set new groups. 

[EFAULT] The address specified for gidset is outside the process address space. The reliable 

detection of this error is implementation dependent. 

[EINVAL] ngroups is greater than NGROUPS or not positive. 

[EINVAL] An entry in gidset is not a valid group ID. 

AUTHOR 

setgroups ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

getgroups(2), initgroups(3C) 

STANDARDS CONFORMANCE 

setgroups ( ) : AES 
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NAME 

sethostname - set name of host cpu 

SYNOPSIS 

ttinclude <unistd.h> 

int sethostname (const char *name, size_t namelen); 

DESCRIPTION 

sethostname ( ) sets the name of the host processor to name, which has a length of namelen characters, 
sethostname ( ) is normally executed by hostname (see hostname{l)) in the /etc/rc script at sys- 
tem boot time. Host names are limited to MAXHOSTNAMELEN characters, as defined in 
<sys/param.h>. 

RETURN VALUE 

Upon successful completion, sethostname ( ) returns 0; otherwise it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

sethostname ( ) fails if any of the following conditions are encountered: 

[EPERM] It is not executed by a user having appropriate privileges. 

[EFAULT] name points to an illegal address. The reliable detection of this error is implementa- 

tion dependent. 

AUTHOR 

sethostname ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

hostname(l), uname(l), gethostname(2), uname(2), privilege(5). 
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NAME 

setpgid, setpgrp2 - set process group ID for job control 

SYNOPSIS 

#include <unistd.h> 

int setpgid(pid_t pid, pid_t pgid) ; 
int setpgrp2 (pid_t pid, pid_t pgid) ; 

DESCRIPTION 

setpgid ( ) or setpgrp2 ( ) causes the process specified by pid to join an existing process group or 
create a new process group within the session of the calling process. The process group ID of the process 
whose process ID is pid is set to pgid. lipid is zero, the process ID of the calling process is used. If pgid is 
zero, the process ID of the indicated process is used. The process group ID of a session leader does not 
change. 

setpgrp2 ( ) is provided for backward compatibility only. 

RETURN VALUE 

Upon successful completion, setpgid () and setpgrp2() return zero; otherwise, they return -1 and 
set errno to indicate the error. 

ERRORS 

setpgid ( ) and setpgrp2 ( ) fail and no change occurs if any of the following conditions are encoun- 
tered: 

[EACCES] The value of pid matches the process ID of a child process of the calling process and 

the child process has successfully executed one of the exec(2) functions. 

[EINVAL] The value of pgid is less than zero or is outside the range of valid process group ID 

values. 

[EPERM] The process indicated by pid is a session leader. 

[EPERM] The value of pid is valid but matches the process ID of a child process of the calling 

process, and the child process is not in the same session as the calling process. 

[EPERM] The value of pgid does not match the process ID of the process indicated by pid and 

there is no process with a process group ID that matches the value of pgid in the same 
session as the calling process. 

[ESRCH] The value of pid does not match the process ID of the calling process or of a child pro- 

cess of the calling process. 

AUTHOR 

setpgid ( ) and setpgrp2 ( ) were developed by HP and the University of California, Berkeley. 

SEE ALSO 

bsdproc(2), exec(2), exit(2), fork(2), getpid(2), kill(2), setsid(2), signal(2), termio(7). 

STANDARDS CONFORMANCE 

setpgid ( ) : AES, XPG3, XPG4, FIPS 151-2, POSK.l 
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NAME 

setresuid, setresgid - set real, effective, and saved user and group IDs 

SYNOPSIS 

#include <unistd.h> 

int setresuid (uid_t ruid, uid_t euid, uid_t suid); 
int setresgid (gid_t rgid, gid_t egid, gid_t sgid) ; 

DESCRIPTION 

setresuid ( ) sets the real, effective and/or saved user ID of the calling process. 

If the current real, effective or saved user ID is equal to that of a user with having appropriate privileges, 
setresuid ( ) sets the real, effective and saved user IDs to ruid, euid, and suid, respectively. Otherwise, 
setresuid ( ) only sets the real, effective, and saved user IDs if ruid, euid, and suid each match at least 
one of the current real, effective, or saved user IDs. 

If ruid, euid, or suid is -1, setresuid() leaves the current real, effective or saved user ID unchanged. 

setresgid ( ) sets the real, effective and/or saved group ID of the calling process. 

If the current real, effective or saved user ID is equal to that of a user having appropriate privileges, 
setresgid ( ) sets the real, effective, and saved group IDs to rgid, egid, and sgid, respectively. Other- 
wise, setresgid ( ) only sets the real, effective and saved group IDs if rgid, egid, and sgid each match at 
least one of the current real, effective or saved group IDs. 

If rgid, egid, or sgid is -1, setresgid ( ) leaves the current real, effective or saved group ID unchanged. 

RETURN VALUE 

Upon successful completion, setresuid ( ) and setresgid ( ) return 0; otherwise, they return -1 and 
set errno to indicate the error. 

ERRORS 

setresuid ( ) and setresgid ( ) fail if any of the following conditions are encountered: 

[EINVAL] ruid, euid, or suid (rgid, egid, or sgid) is not a valid user (group) ID. 

[EPERM] None of the conditions above are met. 

AUTHOR 

setresuld() and setresgidO were developed by HP. 

SEE ALSO 

exec(2), getuid(2), setuid(2). 
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NAME 

setsid, setpgrp - create session and set process group ID 

SYNOPSIS 

#include <unistd.h> 

pid_t setsid (void) ; 
pid_t setpgrp (void) ; 

DESCRIPTION 

If the calling process is not a process group leader, setsid () or setprgpO creates a new session. The 
calling process becomes the session leader of this new session, becomes the process group leader of a new 
process group, and has no controlling terminal. The process group ID of the calling process is set equal to 
the process ID of the calling process. The calling process is the only process in the new process group, and 
the only process in the new session. 

setprgp ( ) is provided for backward compatibility only. 

RETURN VALUE 

setprgp ( ) returns the value of the process group ID of the calling process. 

Upon successful completion, setsid ( ) returns the value of the new process group ID of the calling pro- 
cess. Otherwise, a value of -1 is returned, and errno is set to indicate the error. 

ERRORS 

No change occurs if any of the following conditions are encountered. In addition, sets id () fails when 
any of the following conditions occur: 

[EPERM] The calling process is already a process group leader. 

[EPERM] The process group ID of a process other than the calling process matches the process 

ID of the calling process. 

AUTHOR 

setprgpO and setsidO were developed by HP and AT&T. 

SEE ALSO 

exec(2), exit(2), fork(2), getpid(2), kill(2), setpgid(2), signal(2), termio(7). 

STANDARDS CONFORMANCE 

setsid ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

setpgrp ( ) : SVID2, XPG2 
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NAME 

setuid, setgid - set user and group IDs 

SYNOPSIS 

ttinclude <unistd.h> 

int setuid (uid_t uid) ; 
int setgid (gid_t gid) ; 

DESCRIPTION 

setuid ( ) sets the real-user-ID (ruid),effective-user-lD (euid), and/or saved-user-ID (suid) of the calling 
process. The super-user's euid is zero. The following conditions govern setuid's behavior: 

• If the euid is zero, setuid () sets the ruid, euid, and suid to uid. 

• If the euid is not zero, but the argument uid is equal to the ruid or the suid, setuid ( ) sets the 
euid to uid; the ruid and suid remain unchanged. (If a set-user-ID program is not running as 
super-user, it can change its euid to match its ruid and reset itself to the previous euid value.) 

• If euid is not zero, but the argument uid is equal to the euid, and the calling process is a member 
of a group that has the PRIV_SETRUGID privilege (see privgrp(4)), setuid ( ) sets the ruid to 
uid; the euid and suid remain unchanged. 

setgid ( ) sets the real-group-ID (rgid), effective-group-ID (egid), and/or saved-group-ID (sgid) of the cal- 
ling process. The following conditions govern setgid ( ) 's behavior: 

• If euid is zero, s et gid ( ) sets the rgid and egid to gid . 

• If euid is not zero, but the argument gid is equal to the rgid or the sgid, setgid ( ) sets the egid 
to gid ; the rgid and sgid remain unchanged. 

• If euid is not zero, but the argument gid is equal to the egid, and the calling process is a member 
of a group that has the PRIV_SETRUGID privilege (see privgrpiA)), setgid () sets the rgid to 
gid; the egid and sgid remain unchanged. 

RETURN VALUE 

Upon successful completion, setuid () and setgid () returned 0; otherwise, they return -1 and set 
errno to indicate the error. 

ERRORS 

setuid ( ) and setgid ( ) fail and return - 1 if any of the following conditions are encountered: 

[EPERM] None of the conditions above are met. 

[EINVAL] uid (gid) is not a valid user (group) ID. 

WARNINGS 

It is recommended that the PRIV_SETRUGID capability be avoided, as it is provided for backward compa- 
tibility. This feature may be modified or dropped from future HP-UX releases. When changing the real user 
ID and real group ID, use of setresuid() and setresgidO (see setresuid(2)) are recommended 
instead. 

AUTHOR 

setuid ( ) was developed by AT&T, the University of California, Berkeley, and HP. 

setgid ( ) was developed by AT&T. 

SEE ALSO 

exec(2), getprivgrp(2), getuid(2), setresuid(2) privgrp(4). 

STANDARDS CONFORMANCE 

setuid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

setgid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

shmctl - shared memory control operations 

SYNOPSIS 

# include <sys/shm.h> 

int shmctl (int shmid, lnt cmd, struct shmid_ds *buf ) ; 

DESCRIPTION 

shmctl ( ) provides a variety of shared memory control operations as specified by cmd. The following 
cmds are available: 

IPC_STAT Place the current value of each member of the data structure associated with shmid 
into the structure pointed to by buf. The contents of this structure are defined in the 

S vvoin " J- 

IPC_SET Set the value of the following members of the data structure associated with shmid to 

the corresponding value found in the structure pointed to by buf: 

shm_perm.uid 
shm_perm.gid 
shm_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an effective user ID equal to either that of a user hav- 
ing appropriate privileges or to the value of either shm_perm.uid or shm_perm.cuid in the data 
structure associated with shmid. 

IPC_RMID 

Remove the shared memory identifier specified by shmid from the system and destroy the shared memory 
segment and data structure associated with it. If the segment is attached to one or more processes, then 
the segment key is changed to IPC_PRIVATE and the segment is marked removed. The segment disap- 
pears when the last attached process detaches it. This cmd can only be executed by a process that has an 
effective user ID equal to either that of a user with appropriate privileges or to the value of either 
shm_perm.uidor shm_perm. cuid in the data structure associated with shmid. 

SHM_LOCK 

Lock the shared memory segment specified by shmid in memory. This cmd can only be executed by a pro- 
cess that either has an effective user ID equal to that of a user having appropriate privileges or has an 
effective user ID equal to the value of either shm_perm.uid or shmjperm.cuid in the data struc- 
ture associated with shmid and has PRIV_MLOCK privilege (see setprivgrp() description, get- 
privgrp(2)). 

SHM_UNLOCK 

Unlock the shared memory segment specified by shmid . This cmd can only be executed by a process that 
either has an effective user ID equal to a user having appropriate privileges or has an effective user ID 
equal to the value of either shm_perm . uid or shm_perm . cuid in the data structure associated with 
shmid and has PR I V_MLOCK privilege (see setprivgrpO description, getprivgrp (2)). 

RETURN VALUE 

shmctl ( ) returns a value of upon successful completion; otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

shmctl ( ) fails if any of the following conditions are encountered (see DEPENDENCIES): 

[EINVAL] shmid is not a valid shared memory identifier. 

[EINVAL] cmd is not a valid command. 

[EACCES] cmd is equal to IPC_STAT and Read operation permission is denied to the calling 

process (see shared memory operation permissions in glossary (9)). 

[EPERM] cmd is equal to IPC_RMID, IPC_SET, SHM_LOCK, or SHM_UNLOCK and the 

effective user ID of the calling process is not equal to that of a user having appropriate 
privileges and it is not equal to the value of either shmjperm.uid or 
shm perm, cuid in the data structure associated with shmid. 
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[EPERM] cmd is equal to SHM_LOCKor SHM_UNLOCK and the effective user ID of the calling 

process is not equal to that of a user having appropriate privileges and the calling 
process does not have PR IV_MLOCK privilege (see setprivgrpO description, 
getprivgrp(2)). 

[EINVAL] cmd is equal to SHM_UNLOCK and the shared-memory segment specified by shmid is 

not locked in memory. 

DEFAULT] buf points to an illegal address. The reliable detection of this error is implementation 

dependent. 

[ENOMEM] cmd is equal to SHM_LOCK and there is not sufficient lockable memory to fill the 

request. 

EXAMPLES 

The following call to shmctl ( ) locks in memory the shared memory segment represented by myshmid. 
This example assumes the process has a valid shmid, which can be obtained by calling shmget(2). 

shmctl (myshmid, SHMJLOCK, 0); 

The following call to shmctl () removes the shared memory segment represented by myshmid. This 
example assumes the process has a valid shmid, which can be obtained by calling shmget ( ) (see 
shmget(2). 

shmctl (myshmid, IPC_RMID, 0); J 

DEPENDENCIES 
Series 300/400 

An additional error condition can occur on Series 300/400 systems: 

[EACCES] shmid is the id of a shared memory segment currently being used by the system to 

implement other features (see graphics(7) and iomap(7)). 

AUTHOR 

shmctl ( ) was developed by AT&T and HP. 

SEE ALSO 

ipcrm(l), ipcs(l), shmget(2), shmop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

shmctl ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

shmget - get shared memory segment 

SYNOPSIS 

#include <sys/shm.h> 

int shmget (key_t key, size_t size, int shmf lg) ; 

DESCRIPTION 

shmget ( ) returns the shared memory identifier associated with key . 

A shared memory identifier and associated data structure and shared memory segment of size size bytes 
(see glossary^)) are created for key if one of the following is true: 

• key is equal to IPCJPRIVATE. This call creates a new identifier, subject to available resources. 
The identifier will never be returned by another call to shmget ( ) until it has been released by a 
call to shmctl ( ) . The identifier should be used among the calling process and its descendents; 
however, it is not a requirement. The resource can be accessed by any process having the proper 
permissions. 

• key does not already have a shared memory identifier associated with it, and (shmflg & 
IPC_CREAT) is 'true". 

Upon creation, the data structure associated with the new shared memory identifier is initialized as fol- 
lows: 

• shm_perm.cuid, shm_perm.uid, shm_perm.cgid, and shm_perm.gid are set equal to 
the effective user ID and effective group ID, respectively, of the calling process. 

• shm_perm.cuid, The low-order 9 bits of shm_perm.mode are set equal to the low-order 9 
bits of shmflg. shm_segsz is set equal to the value of size. 

• shm_lpid, shm_nattch, shm_at ime, and shm_dtime are set equal to 0. 

• shm_ctime is set equal to the current time. 

EXAMPLES 

The following call to shmget ( ) returns a unique shmid for the newly created shared memory segment of 
4096 bytes: 

int myshmid; 

myshmid = shmget (IPCJPRIVATE, 4096, 0600); 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a shared memory identifier is returned. Other- 
wise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

shmget ( ) fails if any of the following conditions are encountered: 

[EINVAL] size is less than the system-imposed minimum or greater than the system-imposed 

maximum. 

[EACCES] A shared memory identifier exists for key but operation permission (see glossary (9)) 

as specified by the low-order 9 bits of shmflg would not be granted. 

[EINVAL] A shared memory identifier exists for key but the size of the segment associated with 

it is less than size and size is not equal to zero. 

[ENOENT] A shared memory identifier does not exist for key and (shmflg & IPC_CREAT) is 

"false". 

[ENOSPC] A shared memory identifier is to be created but the system-imposed limit on the max- 

imum number of allowed shared memory identifiers system wide would be exceeded. 

[ENOMEM] A shared memory identifier and associated shared memory segment are to be created, 
but the amount of available physical memory is not sufficient to fill the request. 

[EEXIST] A shared memory identifier exists for key but ( (shmflg & IPC_CREAT) && (shmflg & 

IPC_EXCL))is"true". 
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SEE ALSO 

ipcrm(l), ipcs(l), shmctl(2), shmop(2), stdipc(3C). 

STANDARDS CONFORMANCE 

shmget ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

shmat, shmdt - shared memory operations 

SYNOPSIS 

#include <sys/shm.h> 

char *shmat(int shmid, void *shmaddr, int shmflg); 
int shmdt (void *shmaddr) ; 

DESCRIPTION 

shmat ( ) attaches the shared memory segment associated with the shared memory identifier specified by 
shmid to the data segment of the calling process. 

Series 700/800 Systems 

If the shared memory segment is not already attached, shmaddr must be specified as zero and the 
segment is attached at a location selected by the operating system. That location is identical in all 
processes accessing that shared memory object. 

If the shared memory segment is already attached, a non-zero value of shmaddr is accepted, provided 
the specified address is identical to the current attach address of the segment. 

Series 300/400 Systems 

shmaddr can be specified as a non-zero value as a machine-dependent extension (see DEPENDENCIES 
below). However, those systems do not necessarily guarantee that a given shared memory object 
appears at the same address in all processes that access it, unless the user specifies an address. 

The segment is attached for reading if (shmflg & SHM_RDONLY) is "true"; otherwise it is attached for 
reading and writing. It is not possible to attach a segment for write only. 

shmdt ( ) detaches from the calling process's data segment the shared memory segment located at the 
address specified by shmaddr. 

RETURN VALUE 

Upon successful completion, the return value is as follows: 

shmat ( ) returns the data segment start address of the attached shared memory segment. 

shmdt ( ) returns a value of 0; otherwise, a value of -1 is returned and errno is set to indicate the 
error. 

ERRORS 

shmat ( ) fails and does not attach the shared memory segment if any of the following conditions are 
encountered (see DEPENDENCIES): 

[EINVAL] shmid is not a valid shared memory identifier. 

[EACCES] Operation permission is denied to the calling process. 

[ENOMEM] The available data space is not large enough to accommodate the shared memory seg- 

ment. 

[EINVAL] shmaddr is not zero and the machine does not permit non-zero values or shmaddr is 

not equal to the current attach location for the shared memory segment. 

[EMFILE] The number of shared memory segments attached to the calling process exceed the 

system-imposed limit. 

shmdt ( ) fails and returns - 1 if the following condition is encountered: 

[EINVAL] shmaddr is not the data segment start address of a shared memory segment. 

EXAMPLES 

The following call to shmat attaches the shared memory segment to the process. This example assumes the 
process has a valid shmid, which can be obtained by calling shmget(2). 

char *shmptr / *shmat(); 

shmptr = shmat (myshmid, (char *)0, 0); 

The following call to shmdt ( ) then detaches the shared memory segment. 
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shmdt (shmptr) ; 

DEPENDENCIES 
Series 300/400 

shmaddr can be non-zero, and if it is, the segment is attached at the address specified by one of the follow- 
ing criteria: 

It shmaddr is equal to zero, the segment is attached at the first available address as selected by the system. 
The selected value varies for each process accessing that shared memory object. 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is "true", the segment is attached at the address 
given by (shmaddr - (shmaddr % SHMLBA)). The character % is the C language modulus operator. 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is "false", the segment is attached at the address 
given by shmaddr. 

This form of shmat ( ) fails and does not attach the shared memory segment if any of the following condi- 
tions are encountered: 

[EACCES] shmid is the ID of a shared memory segment currently being used by the system to 

implement other features (see graphics(7) and iomap(7)). 

[EINVAL] shmaddr is not equal to zero, and the value of (shmaddr - (shmaddr % SHMLBA)) is 

an illegal address. 

[EINVAL] shmaddr is not equal to zero, (shmflg & SHM_RND) is "false", and the value of 

shmaddr is an illegal address. 

[ENOMEM] The calling process is locked (see plock(2)) and there is not sufficient lockable memory 

to support the process-related data structure overhead. 

Series 700/800 

shmat ( ) fails and returns -1 if the following is encountered: 

[EINVAL] The calling process is already attached to shmid . 

SEE ALSO 

ipcs(l), exec(2), exit(2), fork(2), shmctl(2), shmget(2), stdipc(3C). 

STANDARDS CONFORMANCE 

shmat ( ) : SVTD2 [Series 300/400 only], XPG2, XPG3, XPG4 

shmdt ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

shutdown - shut down a socket 

SYNOPSIS 

lnt shutdown ( int s , int how) ; 

DESCRIPTION 

The shutdown ( ) system call is used to shut down a socket. In the case of a full-duplex connection, 
shutdown ( ) can be used to either partially or fully shut down the socket, depending upon the value of 
how: 

how Interpretation 

Further receives are disallowed 

1 Further sends are disallowed 

2 Further sends and receives are disallowed 

The s parameter is a socket descriptor for the socket to be shut down. 

Once the socket has been shut down for receives, all further recv ( ) calls return an end-of-file condition. 
A socket that has been shut down for sending causes further send ( ) calls to return an EPIPE error and 
send the SIGPIPE signal. After a socket has been fully shut down, operations other than recv( ) and 
send ( ) return appropriate errors, and the only other thing that can be done to the socket is a c lose ( ) . 

Multiple shutdowns on a connected socket and shutdowns on a socket that is not connected might not 
return errors. 

A shutdown ( ) on a connectionless socket, such as SOCK_DGRAM , only marks the socket as unable 
to do further send() or recv() calls, depending upon how . Once this type of socket has been disabled 
for both sending and receiving data, it becomes fully shut down. For SOCK_STREAM sockets, if how is 1 
or 2, the connection begins to be closed gracefully in addition to the normal actions. However, the 
shutdown ( ) call does not wait for the completion of the graceful disconnection. The disconnection is 
complete when both sides of the connection have done a shutdown ( ) with how equal to 1 or 2. Once 
the connection has been completely terminated, the socket becomes fully shut down. The SO_LINGER 
option (see socket(2)) does not have any meaning for the shutdown ( ) call, but does for the close ( ) 
call. For more information on how the close () call interacts with sockets, see socket(2). 

If a shutdown ( ) is performed on a SOCK_STREAM socket that has a listen ( ) pending on it, that 
socket becomes fully shut down when how = 1. 

AF.CCITT only: 

The how parameter behaves differently if the socket is of the the AP_CCITT address family. If how is set 
to the specified socket can no longer receive data. The SVC is not cleared and remains intact. However, 
if data is subsequently received on the SVC, it is cleared. The connection is not completely down until either 
side executes a close () or shutdown () with how set to 1 or 2. 

If how is set to 1 or 2, the SVC can no longer send or receive data and the SVC is cleared. The socket's 
resources are maintained so that data arriving prior to the shutdown ( ) call can still be read. 

RETURN VALUE 

Upon successful completion, shutdown ( ) returns 0; otherwise it returns -1 and errno is set to indicate 
the error. 

ERRORS 

shutdown ( ) fails if any of the following conditions are encountered: 

[EBADF] s is not a valid descriptor. 

[ENOTSOCK] s is a file, not a socket. 

[EINVAL] The specified socket is not connected. 

AUTHOR 

shutdown ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

close(2), connect(2), socket(2). 
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NAME 

sigaction - examine and change signal action 

SYNOPSIS 

#include <signal.h> 

int sigaction ( 

int sig, 

const struct sigaction *act, 

struct sigaction *oact 
) . 

DESCRIPTION 

sigaction ( ) allows the calling process to examine and specify the action to be taken on delivery of a 
specific signal. The argument sig specifies the signal; acceptable values are defined in <signal . h>. More 
details on the semantics of specific signals can be found in the signal(5) manual entry. 

The s igact ion structure and type sigset_t are defined in <s ignal . h>. 

act and oact are pointers to sigaction structures that include the following elements: 

void [* sajiandler) () ; 

s i g s e t_t sa_mask ; 
int sajlags ; 

Unless it is a null pointer, the argument act points to a structure specifying the action to be taken when 
delivering the specified signal. If the argument oact is not a null pointer, the action previously associated 
with the signal is stored in the location pointed to by oact. If the argument act is a null pointer, signal han- 
dling is unchanged; thus sigaction ( ) can be used to inquire about the current handling of a given sig- 
nal. 

The sajiandler member of the sigaction structure is assigned one of three values: SIG_DFL, 
SIG_IGN, or a function address. The actions prescribed by these values are as follows: 

SIG_DFL Execute default action for signal. 

Upon receipt of the signal sig, the default action (specified on signal(5)) is per- 
formed. The default action for most signals is to terminate the process. 

A pending signal is discarded (whether or not it is blocked) if sigaction ( ) is 
set to SIG_DPL for a pending signal whose default action is to ignore the signal 
(as in the case of SIGCHLD). 

S I G_I GN Ignore the signal. 

Setting a signal action to SIG_IGN causes a pending signal to be discarded, 
whether or not it is blocked. 

The SIGKILLand SIGSTOP signals cannot be ignored. 

function address Catch the signal. 

Upon receipt of the signal sig, the receiving process executes the signal-catching 
function pointed to by sajiandler . The signal-catching function is entered as a C- 
language function call. Details on the arguments passed to this function can be 
found in the signal(5) manual entry. 

The signals SIGKILL and SIGSTOP cannot be caught. 

When a signal is caught by a signal-catching function installed by sigaction, a new mask is calculated 
and installed for the duration of the signal-catching function, or until a call is made to sigproc- 
mask() or sigsuspend() (see sigprocmask(2) and sigsuspend(2)). This mask is formed by taking 
the union of the current signal mask, the signal to be delivered, and unless the SA_RESETHAND flag 
is set (see below), the signal mask specified in the sa_mask field of the sigaction structure associ- 
ated with the signal being delivered. If and when the signal-catching function returns normally, the 
original signal mask is restored. 

Once an action is installed for a specific signal, it remains installed until another action is explicitly 
requested, or until one of the exec (2) functions is called. 
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If the previous action for sig was established by signal(2), the values of the fields returned in the 
structure pointed to by oact are unspecified; in particular, oact->sa_handler is not necessarily the 
same value passed to signal ( ) . However, if a pointer to the same structure or a copy thereof is 
passed to a subsequent call to sigaction ( ) via the act argument, handling of the signal is rein- 
stated as if the original call to signal () were repeated. 

The set of signals specified by the sajnask field of the sigaction structure pointed to by the act 
argument cannot block the SIGKILL or SIGSTOP signal. This is enforced by the system without 
causing an error to be indicated. 

The sajlags field in the sigaction structure can be used to modify the behavior of the specified 
signal. The following flag bits, denned in the <signal . h> header, can be set in sajlags: 

SA_NOCLDSTOP Do not generate SIGCHLD when untraced children stop (see ptrace{2)). 

SA_ONSTACK Use the space reserved by sigspace () for signal processing. 

SA_RESETHAND Use the semantics of signal (). The signal mask specified by the 
sajnask field is not used when setting up the effective signal mask for the 
signal handler. If the signal is not one of those marked "not reset when 
caught" (see signal(5)\ the default action for the signal is reinstated when 
the signal is caught, prior to entering the signal-catching function. The 
"not reset when caught" distinction is insignificant when sigaction ( ) 
is called and SA_RESETHAND is not set. 

RETURN VALUE 

Upon successful completion, sigaction ( ) returns 0; otherwise it returns -1 and sets errno to indicate 
the error. 

ERRORS 

sigaction ( ) fails and no new signal-catching function is installed if any of the following conditions is 
encountered: 

[EINVAL] The value of the sig argument is not a valid signal number, or an attempt is 

made to supply an action other than SIG_DFLfor the SIGKILL or SlGSTOP 
signal. 

[EFAULT] act or oact points to an invalid address. The reliable detection of this error is 

implementation dependent. 

AUTHOR 

sigact ion ( ) was derived from the IEEE POSIX 1003.1-1988 Standard. 

SEE ALSO 

ptrace(2), sigprocmask(2), sigpending(2), sigspace(2), sigsuspend(2), sigsetops(3C), signal(5). 

STANDARDS CONFORMANCE 

sigaction ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

sigblock - block signals 

SYNOPSIS 

#include <signal.h> 

long sigblock (long mask); 

DESCRIPTION 

sigblock ( ) causes the signals specified in mask to be added to the set of signals currently being blocked 
from delivery. Signal i is blocked if the i-thbit in mask is 1, as specified with the macro sigmask(i) . 

It is not possible to block signals that cannot be ignored, as documented in signal(5); this restriction is 
silently imposed by the system. 

Use s igsetmask ( ) to set the mask absolutely (see sigsetmask{2)). 

RETURN VALUE 

sigblock ( ) returns the previous set of masked signals. 

EXAMPLES 

The following call to sigblock ( ) adds the SIGUSR1 and SI6USR2 signals to the mask of signals 
currently blocked for the process: 

long oldmask; 

oldmask = sigblock (sigmask (SIGUSR1) I sigmask (SIGUSR2)); 

WARNINGS 

Do not use s igblock ( ) in conjunction with the facilities described under sigset(2V). 

AUTHOR 

sigblock ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

kill(2), sigprocmask(2), sigsetmask(2), sigvector(2). 
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NAME 

signal - specify what to do upon receipt of a signal 

SYNOPSIS 

ttinclude <signal.h> 

void (*signal(lnt sig, void (*action) (int) ) ) (int) ; 

DESCRIPTION 

signal ( ) allows the calling process to choose one of three ways to handle the receipt of a specific signal. 
sig specifies the signal and action specifies the choice. 

Acceptable values for sig are defined in <signal .h>. The specific signals are described in full in the sig- 
nal(5) manual entry. 

The value of the action argument specifies what to do upon the receipt of signal sig, and should be one of 
the following: 

SIG_DPL Execute the default action, which varies depending on the signal. The default action for 
most signals is to terminate the process (see signal(S)). 

A pending signal is discarded (whether or not it is blocked) if action is set to SIG_DPL 
but the default action of the pending signal is to ignore the signal (as in the case of 
SIGCLD). 

SIG_IGN Ignore the signal. 

When signal ( ) is called with action set to SIG_IGN and an instance of the signal 
sig is pending, the pending signal is discarded, whether or not it is blocked. 

SIGKILL and SIGSTOP signals cannot be ignored. 

address Catch the signal. 

Upon receipt of signal sig, reset the value of action for the caught signal to SIG_DFL 
(except signals marked with "not reset when caught"; see signal(5)), call the signal- 
catching function to which address points, and resume executing the receiving process at 
the point where it was interrupted. 

The signal-catching function is called with the following three parameters: 

sig The signal number. 

code A word of information usually provided by the hardware. 

scp A pointer to the machine-dependent structure sigcontext defined in 
<signal.h>. 

Depending on the value of sig, code can be zero and/or scp can be NULL. The meanings of code and scp 
and the conditions determining when they are other than zero or NULL are implementation dependent 
(see DEPENDENCIES below). It is possible for code to always be zero, and scp to always be NULL. 

The pointer scp is valid only during the context of the signal-catching function. 

The signals SIGKILL and SIGSTOP cannot be caught. 

RETURN VALUE 

Upon successful completion, signal ( ) returns the previous value of action for the specified signal sig. 
Otherwise, a value of SIG_ERR is returned and errno is set to indicate the error. 

ERRORS 

signal () fails if the following is true: 

[EINVAL] sig is an illegal signal number, or is equal to SIGKILL or SIGSTOP. 

EXAMPLES 

The following call to signal () sets up a signal-catching function for the SIGINT signal: 

void myhandler(); 
(void) signal (SIGINT, myhandler) ; 
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WARNINGS 

signal ( ) should not be used in conjunction with the facilities described under bsdproc(2), sigaction(2), 
sigset(2V), or sigvector(2). 

signal ( ) does not detect an invalid value for action, and if it does not equal SIG_DPL or SIG_IGN, or 
point to a valid function address, subsequent receipt of the signal sig causes undefined results. 

DEPENDENCIES 
Series 300/400 

The code word is always zero for all signals except SIGILL and SIGPPE. For SIGILL, code has the fol- 
.lOwmg values: 

illegal instruction; 

6 check instruction; 

7 TRAPV; 

8 privilege violation. 

Refer to the MC6800xx processor documentation for more detailed information about the meaning of the 
SIGILL errors. 



For SIGPPE, code has the following values: 

software floating point exception; 

5 integer divide-by-zero. 

Ox &xxxxocx any value with the high-order bit set indicates an exception while using the 

HP 98248 floating-point accelerator. The value of (code &~ 0x8000000) is the value of 
the HP 98248 status register. Refer to the HP 98248 documentation for more detailed 
information. 

other any other value indicates an exception while using the MC68881 or MC68882 

floating-point coprocessor. The value of code is the value of the MC68881 or MC68882 
status register. Refer to the MC68881 documentation for more detailed information. 

Series 700/800 

The structure pointer scp is always defined. 

The code word is always zero for all signals except SIGILL and SIGPPE. For SIGILL, code has the fol- 
lowing values: 

8 illegal instruction trap; 

9 break instruction trap; _ 

10 privileged operation trap; I 

11 privileged register trap. ^ 

For SIGFPE, code has the following values: 

12 overflow trap; 

1 3 conditional trap ; 

14 assist exception trap; 
2 2 assist emulation trap. 

As defined by the IEEE POSIX Standard, HP-UX on Series 700/800 systems does not raise an exception on 
floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by 
isinf(3M). 

AUTHOR 

signal ( ) was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO 

kill(l), init(lM), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), 
signal(5). 

STANDARDS CONFORMANCE 

signal ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 
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NAME 

sigpause - atomically release blocked signals and wait for interrupt 

SYNOPSIS 

#include <signal.h> 

long sigpause (long mask); 

DESCRIPTION 

sigpause () blocks signals according to the value of mask in the same manner as sigsetmask(2), then 
atomically waits for an unmasked signal to arrive. On return sigpause ( ) restores the current signal 
mask to the value that existed before the sigpause ( ) call. When no signals are to be blocked, a value of 
OL is used for mask. 

In normal usage, a signal is blocked using sigblock ( ) (see sigblock(2)). To begin a critical section, vari- 
ables modified on the occurrence of the signal are examined to determine that there is no work to be done, 
and the process pauses, awaiting work by using s igpause ( ) with the mask returned by s igblock ( ) . 

RETURN VALUE 

sigpause ( ) terminates when it is interrupted by a signal. When sigpause ( ) terminates, it returns -1 
and sets errno to EINTR. 

EXAMPLES 

The following call to s igpause ( ) waits until the calling process receives a signal: 

sigpause (OL); 

The following example blocks the SIGIO signal until sigpause ( ) is called. When a signal is received at 
the sigpause ( ) statement, the signal mask is restored to its value before sigpause ( ) was called: 

long savemask; 

savemask = sigblock (sigmask (SIGIO)); 

/* critical section */ 

sigpause (savemask); 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvectorO can 
affect the behavior described on this page. 

Do not use s igpause ( ) in conjunction with the facilities described under sigset(2V). 

AUTHOR 

sigpause ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

sigblock(2), sigsetmask(2), sigsuspend(2), sigvector(2). 
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NAME 

sigpending - examine pending signals 

SYNOPSIS 

ttinclude <signal.h> 

int sigpending (sigset_t *set); 

DESCRIPTION 

sigpending ( ) stores sets of signals that are blocked from delivery and are pending to the calling pro- 
cess, at the location pointed to by set. 

RETURN VALUE 

Upon successful completion, sigpending () returns a value of 0; otherwise it returns -1 and sets 
errno to indicate the error. 

ERRORS 

sigpending ( ) fails if the following condition is encountered: 

[EFAULT] set points to an invalid address. The reliable detection of this error is implementation 

dependent. 

AUTHOR 

sigpending ( ) was derived from the IEEE POSDC 1003.1-1988 Standard. 

SEE ALSO 

sigaction(2), sigsuspend(2), sigprocmask(2), sigsetops(3C), signal(5). 

STANDARDS CONFORMANCE 

sigpending ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

sigprocmask - examine and change blocked signals 

SYNOPSIS 

#include <slgnal.h> 

int sigprocmask ( 

const sigset_t *set, 
sigset_t *oset 
); 

DESCRIPTION 

sigprocmask ( ) allows the calling process to examine and/or change its signal mask. 

Unless it is a null pointer, the argument set points to a set of signals to be used to change the currently 
blocked set. 

The argument how indicates how the set is changed, and consists of one of the following values (see 
<signal.h>): 

SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by 

set. 

SIG__UNBLOCK The resulting set is the intersection of the current set and the complement of the 
signal set pointed to by set. 

SIG_SETMASK The resulting set is the signal set pointed to by set. 

If the argument oset is not a null pointer, the previous signal mask is stored in the location pointed to by 
oset. If set is a null pointer, the value of the argument how is insignificant and the process's signal mask is 
unchanged; thus the call can be used to inquire about currently blocked signals. 

If any pending unblocked signals remain after the call to sigprocmask ( ) , at least one of those signals 
is delivered before the call to sigprocmask ( ) returns. 

It is impossible to block the SIGKILL or SIGSTOP signal. This is enforced by the system without caus- 
ing an error to be indicated. 

The process's signal mask is not changed if s igprocmask ( ) fails for any reason. 

RETURN VALUE 

Upon successful completion, sigprocmask ( ) returns 0; otherwise it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

sigprocmask ( ) fails if any of the following conditions are encountered: 

[EINVAL] The value of the how argument is not equal to one of the defined values. 

[EFAULT] set or oset points to an invalid address. The reliable detection of this error is imple- 

mentation dependent. 

AUTHOR 

sigprocmask ( ) was derived from the IEEE POSIX 1003.1-1988 Standard. 

SEE ALSO 

sigaction(2), sigsuspend(2), sigpending(2), sigsetops(3C), signal(5). 

STANDARDS CONFORMANCE 

sigprocmask ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

sigset, sighold, sigrelse, sigignore, sigpause - signal management 

SYNOPSIS 

ttinclude <signal.h> 

void (*sigset(int sig, void (*func) (int) ) ) (int ) ; 
int sighold(int sig) ; 
int sigrelse (int sig); 
int sigignore (int sig); 
int sigpause (int sig); 

DESCRIPTION 

The system defines a set of signals that can be delivered to a process. The set of signals is defined in sig- 
nal(5), along with the meaning and side effects of each signal. An alternate mechanism for handling these 
signals is defined here. The facilities described here should not be used in conjunction with the other facili- 
ties described under signal(2\ sigvector(2), sigblock(2), sigsetmask(2), sigpause(2) and sigspace(2). 

sigset ( ) allows the calling process to choose one of four ways to handle the receipt of a specific signal. 
sig specifies the signal and func specifies the choice. 

sig can be any one of the signals described under signal(5) except SIGKILL or SIGSTOP. 

func is assigned one of four values: SIG_DFL, SIG_IGN, SIG_HOLD, or a function address. The actions 
prescribed by SIG_DPL and SIG_IGN are described under signal(5). The action prescribed by 
SIG_HOLD and function address are described below: 

SIG_HOLD Hold signal. 

The signal sig is held upon receipt. Any pending signal of this signal type remains held. 
Only one signal of each type is held. 

Note: the signals SIGKILL, SIGCONT, and SIGSTOP cannot be held. 

function address 

Catch signal. 

func must be a pointer to a function, the signal-catching handler, that is called when signal 
sig occurs, s igset ( ) specifies that the process calls this function upon receipt of signal 
sig. Any pending signal of this type is released. This handler address is retained across 
calls to the other signal management functions listed here. Upon receipt of signal sig, the 
receiving process executes the signal-catching function pointed to by func as described 
under signal(5) with the following differences: 

Before calling the signal-catching handler, the system signal action of sig is set to 
SIG_HOLD. During a normal return from the signal-catching handler, the system signal 
action is restored to func and any held signal of this type is released. If a non-local goto 
(longjmp(3C)) is taken, sigrelse () must be called to restore the system signal action to 
func and release any held signal of this type. 

sighold ( ) holds the signal sig. sigrelse ( ) restores the system signal action of sig to that specified 
previously by sigset ( ) . sighold ( ) and sigrelse ( ) are used to establish critical regions of code, 
sighold ( ) is analogous to raising the priority level and deferring or holding a signal until the priority is 
lowered by sigrelse () . 

sigignore ( ) sets the action for signal sig to SIG_IGN (see signal^)). 

sigpause ( ) suspends the calling process until it receives an unblocked signal. If the signal sig is held, it 
is released before the process pauses, s igpause ( ) is useful for testing variables that are changed when 
a signal occurs. For example, s ighold ( ) should be used to block the signal first, then test the variables. 
If they have not changed, call s igpause ( ) to wait for the signal. 

These functions can be linked into a program by giving the - 1V3 option to the Id command (see ld(l)). 

RETURN VALUE 

Upon successful completion, sigset () returns the previous value of the system signal action for the 
specified signal sig. Otherwise, a value of SIG_ERR is returned and ermo is set to indicate the error. 
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SIG_ERR is defined in <signal . h>. 

For the other functions, a value indicates that the call succeeded. A -1 return value indicates an error 
occurred and errno is set to indicate the reason. 

ERRORS 

s i gs et ( ) fails and the system signal action for sig is not changed if any of the following occur: 

[EFAULT] The func argument points to memory that is not a valid part of the process 

address space. Reliable detection of this error is implementation dependent. 

sigset (), sighold(), sigrelse(), sigignore( ), and sigpauseO fail and the system signal 
action for sig is not changed if any of the following occur: 

[EINVAL] sig is nou a vaiiu signal nuniuer. 

[EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that can- 

not be ignored, held, or caught; see signal(5). 

sigpause returns when the following occurs: 

[EINTR] A signal was caught. 

WARNINGS 

These signal facilities should not be used in conjunction with bsdproc(2\ signal(2), sigvector(2), sigblock{2), 
sigsetmask(2), sigpause(2) and sigspace(2). 

SEE ALSO 

kill(l), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). 

STANDARDS CONFORMANCE 

sigset: SVID2 

sighold: SVID2 
sigignore: SVID2 
sigpause: SVID2 
sigrelse:SVID2 
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NAME 

sigsetmask - set current signal mask 

SYNOPSIS 

#include <signal.h> 

long sigsetmask (long mask); 

DESCRIPTION 

sigsetmask ( ) sets the current signal mask (those signals that are blocked from delivery). Signal i is 
blocked if the i-th bit in mask^ as specified with the macro sigmask (i) . is a 1. 

It is not possible to mask signals that cannot be ignored, as documented in signal(5); this restriction is 
silently imposed by the system. 

sigblock ( ) can be used to add elements to the set of blocked signals. 

RETURN VALUE 

The previous set of masked signals is returned. 

EXAMPLES 

The following call to s igsetmask ( ) causes only the SIGUSR1 and SIGUSR2 signals to be blocked: 

long oldmask; 

oldmask = sigsetmask (sigmask (SIGUSR1) I sigmask (SIGUSR2)); 

WARNINGS 

Do not use s igsetmask ( ) in conjunction with the facilities described under sigset(2V). 

AUTHOR 

sigsetmask ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

kill(2), sigblock(2), sigpause(2), sigprocmask(2), sigvector(2). 
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NAME 

sigspace - assure sufficient signal stack space 

SYNOPSIS 

#include <signal.h> 

size_t sigspace ( si ze_t stacksize); 

DESCRIPTION 

sigspace () requests additional stack space that is guaranteed to be available for processing signals 
received by the calling process. 

If the value of stacksize is positive, it specifies the size of a space, in bytes, which the system guarantees to 
be available when processing a signal. If the value of stacksize is zero, any guarantee of space is removed. 
If the value is negative, the guarantee is left unchanged; this can be used to interrogate the current 
guaranteed value. 

When a signal's action indicates that its handler should use the guaranteed space (specified with a sigac- 
tion ( ) , sigvector ( ) , or sigvec ( ) call (see bsdproc(2J), the system checks to see if the process is 
currently using that space. If the process is not currently using that space, the system arranges for that 
space to be available for the duration of the signal handler's execution. If that space has already been made 
available (due to a previous signal) no change is made. Normal stack discipline is resumed when the signal 
handler first using the guaranteed space is exited. 

The guaranteed space is inherited by child processes resulting from a successful fork ( ) system call, but 
the guarantee of space is removed after any exec ( ) system call (seefork(2) and exec{2)). 

The guaranteed space cannot be increased in size automatically, as is done for the normal stack. If the 
stack overflows the guaranteed space, the resulting behavior of the process is undefined. 

Guaranteeing space for a stack can interfere with other memory allocation routines in an implementation- 
dependent manner. 

During normal execution of the program the system checks for possible overflow of the stack. Guaranteeing 
space might cause the space available for normal execution to be reduced. 

Leaving the context of a service routine abnormally, such as by longjmp ( ) (see setjmp(3C)\ removes the 
guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might 
also cause the program to lose forever its ability to automatically increase the stack size, causing the pro- 
gram to be limited to the guaranteed space. 

RETURN VALUE 

Upon successful completion, sigspace () returns the size of the former guaranteed space. Otherwise, it 
returns -1 and sets errno to indicate the error. 

ERRORS 

sigspace ( ) fails and the guaranteed amount of space remains unchanged if the following occurs: 

[ENOMEM] The requested space cannot be guaranteed, either because of hardware limita- 

tions or because some software-imposed limit would be exceeded. 

WARNINGS 

The guaranteed space is allocated using malloc(3C). This use might interfere with other heap management 
mechanisms. 

Methods for calculating the required size are not well developed. 

Do not use s igspace ( ) in conjunction with the facilities described under sigset(2V). 

Do not use s igspace ( ) in conjunction with sigstack(2). 

DEPENDENCIES 
Series 300/400 

The kernel overhead taken in the reserved space is 608 bytes on Series 300/400 systems. This overhead 
must be included in the requested amount. These values are subject to change in future releases. 

AUTHOR 

sigspace ( ) was developed by HP. 
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SEE ALSO 

sigaction(2), sigstack(2), sigvector(2), malloc(3C), setjmp(3C). 
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NAME 

sigstack - set and/or get signal stack context 

SYNOPSIS 

#include <signal.h> 

int sigstack ( 

const struct sigstack *ss, 

struct sigstack *oss 
); 

DESCRIPTION 

sigstack ( ) allows the calling process to indicate to the system an area of its address space to be used for 
processing signals received by the process. 

The correct use of sigstack ( ) is hardware dependent, and therefore is not portable between different 
HP-UX implementations (see DEPENDENCIES below), sigspace ( ) is portable between different HP-UX 
implementations and should be used when the application does not need to know where the signal stack is 
located (see sigspace(2)). sigstack ( ) is provided for compatability with other systems that provide this 
functionality. Users should note that there is no guarantee that functionality similar to this is even possi- 
ble on some architectures. 

If the value of the ss argument is not a null pointer, it is assumed to point to a struct sigstack struc- 
ture, which includes the following members: 

int ssjonstack ; Non-zero when signal stack is in use. 
void *ss_spi Signal stack pointer. 

The value of the ss_onstack member indicates whether the process wants the system to use a signal stack 
when delivering signals; the value of the ss_sp member indicates the desired location (see DEPENDEN- 
CIES) of the signal stack area in the process's virtual address space. 

If the ss argument is a null pointer, the current signal stack context is not changed. 

If the oss argument is not a null pointer, it should point to a variable of type struct sigstack; the 
current signal stack context is returned in that variable. The value stored in the ssjonstack member tells 
whether the process is currently using a signal stack, and if so, the value stored in the ss_sp member is 
the current stack pointer for the stack in use. 

If the oss argument is a null pointer, the current signal stack context is not returned. 

When a signal's action indicates its handler should execute on the signal stack (specified by calling 
sigaction ( ) , sigvector ( ) , or sigvec ( ) (see bsdproc(2))), the system checks to see if the process 
is currently executing on that stack. If the process is not currently executing on the signal stack, the sys- 
tem arranges a switch to the signal stack for the duration of the signal handler's execution. 

The signal stack context is inherited by child processes resulting from a successful f ork( ) system call, 
but the context is removed after an exec ( ) system call (see fork(2) and exec(2)). 

RETURN VALUE 

Upon successful completion, sigstack () returns 0; otherwise, it returns -1 and sets errno to indicate 
the error. 

ERRORS 

sigstack ( ) fails and the signal stack context remains unchanged if the following is true: 

[EFAULT] Either of ss or oss is not a null pointer and points outside the allocated address 

space of the process. The reliable detection of this error is implementation 
dependent. 

WARNINGS 

Do not use sigstack{2) in conjunction with sigspace(2). 

User-defined signal stacks do not grow automatically, as does the normal process stack. If a signal stack 
overflows, the resulting behavior of the process is undefined. 

Methods for calculating the required stack size are not well developed. 
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Leaving the context of a service routine abnormally, such as by long jmp ( ) (see setjmp(3C)), might 
remove the guarantee that the ordinary execution of the program does not extend into the guaranteed 
space. It might also cause the program to lose forever its ability to automatically increase the stack size, 
causing the program to be limited to the guaranteed space. 

DEPENDENCIES 
Series 300/400 

Stack addresses grow from high addresses to low addresses; therefore the signal stack address provided to 
sigstack(2) should point to the end of the space to be used for the signal stack. This address should be 
aligned to a four-byte boundary. 

Series 700/800 

Stack addresses grow from low addresses to high addresses; therefore the signal stack address provided to 
sigstack(2) should point to the beginning of the space to be used for the signal stack. This address should 
be aligned to an eight-byte boundary. 

AUTHOR 

s igs tack ( ) was developed by HP and the University of California, Berkeley. 

SEE ALSO 

sigspace(2), setjmp(3C). 
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NAME 

sigsuspend - wait for a signal 

SYNOPSIS 

ttinclude <signal.h> 

int sigsuspend (const sigset_t *sigmask); 

DESCRIPTION 

sigsuspend ( ) replaces the process's current signal mask with the set of signals pointed to by sigmask, 
then suspends the process until delivery of a signal that either executes a signal handler or terminates the 
process. 

If the signal terminates the process, sigsuspend () never returns. If the signal executes a signal 
handier, sigsuspend ( ) returns after the signal handier returns, and restores the signal mask to the set 
that existed prior to the sigsuspend () call. 

It is impossible to block the SIGKILL or SIGSTOP signal. This is enforced by the system without caus- 
ing an error to be indicated. 

RETURN VALUE 

Since sigsuspend ( ) suspends a process indefinitely, there is no successful completion return value. If a 
return occurs, a value of -1 is returned and er mo is set to indicate the error. 

ERRORS 

sigsuspend ( ) fails if any of the following conditions are encountered: 

[EINTR] s i gsuspend ( ) was interrupted by receipt of a signal. 

[EFAULT] sigmask points to an invalid address. The reliable detection of this error is 

implementation dependent. 

AUTHOR 

sigsuspend ( ) was derived from the IEEE POSIX 1003.1-1988 Standard. 

SEE ALSO 

sigaction(2), sigpending(2), sigprocmask(2), sigsetops(3C), signal(5). 

STANDARDS CONFORMANCE 

sigsuspend ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

sigvector - software signal facilities 

SYNOPSIS 

#include <signal.h> 

int sigvector ( 

int sig, 

const struct sigvec *vec, 

struct sigvec *ovec 
); 

DESCRIPTION 

The system defines a set of signals that can be delivered to a process. The set of signals is defined in sig- 
nal(5), along with the meaning and side effects of each signal. This manual entry, along with those for sig- 
block(2), sigsetmask(2), sigpause(2), and sigspace(2), defines an alternate mechanism for handling these sig- 
nals that ensures the delivery of signals and the integrity of signal handling procedures. The facilities 
described here should not be used in the same program as signal(2). 

With the sigvector () interface, signal delivery resembles the occurrence of a hardware interrupt: the 
signal is blocked from further occurrence, the current process context is saved, and a new one is built. A 
process can specify a handler function to be invoked when a signal is delivered, or specify that a signal 
should be blocked or ignored. A process can also specify that a default action should be taken by the system 
when a signal occurs. It is possible to ensure a minimum amount of stack space for processing signals using 
sigspace ( ) (see sigspace(2)). 

All signals have the same priority. Signal routines execute with the signal that causes their invocation to 
be blocked, although other signals can yet occur. A global signal mask defines the set of signals currently 
blocked from delivery to a process. The signal mask for a process is initialized from that of its parent (nor- 
mally 0). It can be changed with a sigblock ( ) , sigsetmask ( ) , or sigpause ( ) call, or when a sig- 
nal is delivered to the process. 

A signal mask is represented as a long, with one bit representing each signal being blocked. The following 
macro defined in <s ignal . h> is used to convert a signal number to its corresponding bit in the mask: 

ttdefine sigmask(signo) (1L « (signo-1)) 

When a signal condition arises for a process, the signal is added to a set of signals pending for the process. 
If the signal is not currently blocked by the process, it is delivered to the process. When a signal is 
delivered, the current state of the process is saved, a new signal mask is calculated (as described below), 
and the signal handler is invoked. The call to the handler is arranged so that if the signal handling rou- 
tine returns normally, the process resumes execution in the same context as before the signal's delivery. 
If the process wishes to resume in a different context, it must arrange to restore the previous context 
itself. 

When a signal is delivered to a process, a new signal mask is installed for the duration of the process' sig- 
nal handler (or until a sigblock () or sigsetmask () call is made). This mask is formed by taking 
the current signal mask, computing the bit-wise inclusive OB with the value of vec ,sv_mask (see below) 
from the most recent call to sigvector () for the signal to be delivered, and, unless the 
SV_RESETHAND flag is set (see below), setting the bit corresponding to the signal being delivered. When 
the user's signal handler returns normally, the original mask is restored. 

sigvector ( ) assigns a handler for the signal specified by sig. vec and ovec are pointers to sigvec struc- 
tures that include the following elements: 

void ( *sv_handler ) ( ) ; 
long svjmaskt 
long svjlags ; 

If vec is non-zero, it specifies a handler routine (sv_handler), a mask (svjnask) that the system should 
use when delivering the specified signal, and a set of flags (svjlags) that modify the delivery of the signal. 
If ovec is non-zero, the previous handling information for the signal is returned to the user. If vec is zero, 
signal handling is unchanged. Thus, the call can be used to enquire about the current handling of a given 
signal. If vec and ovec point to the same structure, the value of vec is read prior to being overwritten. 
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The svjlags field can be used to modify the receipt of signals. The following flag bits are defined: 

SV_ONSTACK Use the sigspace( ) allocated space. 

SVJ3SDSIG Use the Berkeley signal semantics. 

SVJRESETHAND Use the semantics of signal(2). 

If SV_ONSTACK is set, the system uses or permits the use of the space reserved for signal processing in 
the sigspaceO system call. 

If SV_BSDSIG is set, the signal is given the Berkeley semantics. The following signal is affected by this 
flag: 

SIGCLD In addition to being sent when a child process dies, the signal is also sent when any 

child's status changes from running to stopped. This would normally be used by a 
program such as csh (see csh(T)) when maintaining process groups under Berkeley 
job control. 

If SV_RESETHAND is set, the signal handler is installed with the same semantics as a handler installed 
with signal(2). This affects signal mask set-up during the signal handler (see above) and whether the 
handler is reset after a signal is caught (see below). 

If SV_RESETHAND is not set, once a signal handler is installed, it remains installed until another 
sigvector() call is made or an exec ( ) system call is performed (see exec(2)). If SV_RESETHAND is 
set and the signal is not one of those marked "not reset when caught" under signal(5\ the default action is 
reinstated when the signal is caught, prior to entering the signal-catching function. The "not reset when 
caught" distinction is not significant when sigvector() is called and SV_RESETHAND is not set. 

The default action for a signal can be reinstated by setting svjiandler to SIG_DPL; this default usually 
results in termination of the process. If svjiandler is SIG_IGN the signal is usually subsequently 
ignored, and pending instances of the signal are discarded. The exact meaning of SIG_DPL and 
SIG_IGN for each signal is discussed in signal(5). 

Certain system calls can be interrupted by a signal; all other system calls complete before the signal is 
serviced. The scp pointer described in signal(5) is never null if sigvectorO is supported, scp points 
to a machine-dependent sigcontext structure. All implementations of this structure include the fields: 

int scjsyscall; 

char scjsyscalljxction; 

The value SYS_NOTSYSCALL for the scjsyscall field indicates that the signal is not interrupting a sys- 
tem call; any other value indicates which system call it is interrupting. 

If a signal that is being caught occurs during a system call that can be interrupted, the signal handler is 
immediately invoked. If the signal handler exits normally, the value of the sc_syscall_action field is 
inspected; if the value is SIG_RETURN, the system call is aborted and the interrupted program continues 
past the call. The result of the interrupted call is -1 and errno is set to EINTR. If the value of the 
sc_syscall_action field is SIG_RESTART, the call is restarted. A call is restarted if, in the case of a 
read ( ) or write ( ) system call (see read{2) or write(2)), it had transferred no data. If some data had 
been transferred, the operation is considered to have completed with a partial transfer, and the scjsyscall 
value is SYS_NOTSYSCALL. Other values are undefined and reserved for future use. 

Exiting the handler abnormally (such as with long jmp ( ) — see setjmp(3C)) aborts the call, leaving the 
user responsible for the context of further execution. The value of scp->scjsyscalljxction is ignored when 
the value of scp->sc_syscall is SYS_NOTSYSCALL. scp->scjsyscalljxction is always initialized to 
SIG_RETURN before invocation of a signal handler. When an system call that can be interrupted is 
interrupted by multiple signals, if any signal handler returns a value of SIG_RETURN in 
scp->scjsyscalljxction, all subsequent signal handlers are passed a value of SYS_NOTSYSCALL in 
scp->sc_syscall. 

Note that calls to read ( ) , write ( ) , or ioct 1 ( ) on fast devices (such as disks) cannot be interrupted, 
but I/O to a slow device (such as a printer) can be interrupted. Other system calls, such as those used for 
networking, also can be interrupted on some implementations. In these cases additional values can be 
specified for Programs that look at the values of scp->scjsyscall always should compare them to these 
symbolic constants; the numerical values represented by these constants might vary among implementa- 
tions. System calls that can be interrupted and their corresponding values for scp->sc_syscall are fisted 
below: 
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CaU 


scjsyscall value 


read (slow devices) 


SYS_READ 


readv (slow devices) 


SYS_READV 


write (slow devices) 


SYS_WRITE 


writev (slow devices) 


SYS_WRITEV 


open (slow devices) 


SYS_OPEN 


ioctl (slow requests) 


SYS_IOCTL 


close (slow requests) 


SYS_CLOSE 


wait 


SYS_WAIT 


select 


SYS SELECT 


pause 


SYS_PAUSE 


sigpause 


SYS_SIGPAUSE 


semop 


SYS_SEMOP 


msgsnd 


SYS_MSOSND 


msgrcv 


SYS_MSGRCV 



These system calls are not defined if the preprocessor macro _XPG2 is defined when <signal ,h> is 
included. This is because the XI Open Portability Guide, Issue 2 specifies a different meaning for the sym- 
bol SYS_OPEN (see limits(5)). 

After a fork() or vfork() system call, the child inherits all signals, the signal mask, and the 
reserved signal stack space. 

exec(2) resets all caught signals to the default action; ignored signals remain ignored, the signal mask 
remains unchanged, and the reserved signal stack space is released. 

The mask specified in vec is not allowed to block signals that cannot be ignored, as defined in signal(5). 
This is enforced silently by the system. 

If sigvector ( ) is called to catch SIGCLD in a process that currently has terminated (zombie) chil- 
dren, a SIGCLD signal is delivered to the calling process immediately, or as soon as SIGCLD is 
unblocked if it is currently blocked. Thus, in a process that spawns multiple children and catches 
SIGCLD, it is sometimes advisable to reinstall the handler for SIGCLD after each invocation in case 
there are multiple zombies present. This is true even though the handling of the signal is not reset by the 
system, as with signal(2), because deaths of multiple processes while SIGCLD is blocked in the handler 
result in delivery of only a single signal. Note that the function must reinstall itself after it has called 
wait ( ) or wait 3 ( ) . Otherwise the presence of the child that caused the original signal always causes 
another signal to be delivered. 

RETURN VALUE 

Upon successful completion, sigvector () returns 0; otherwise, it returns -1 and sets errno to indi- 
cate the reason. 

ERRORS 

sigvector ( ) fails and no new signal handler is installed if any of the following conditions are encoun- 
tered: 

DEFAULT] Either vec or ovec points to memory that is not a valid part of the process 

address space. Reliable detection of this error is implementation dependent. 

[EINVAL] sig is not a valid signal number. 

[EINVAL] An attempt was made to ignore or supply a handler for a signal that cannot be 

caught or ignored; see signal(5). 

WARNINGS 

Restarting a select(2) call can sometimes cause unexpected results. If the select ( ) call has a timeout 
specified, the timeout is restarted with the call, ignoring any portion that had elapsed prior to interruption 
by the signal. Normally this simply extends the timeout and is not a problem. However, if a handler 
repeatedly catches signals, and the timeout specified to select ( ) is longer than the time between those 
signals, restarting the select ( ) call effectively renders the timeout infinite. 

sigvector ( ) should not be used in conjunction with the facilities described under sigset(2V). 

AUTHOR 

sigvector ( ) was developed by HP and the University of California, Berkeley. 
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SEE ALSO 

kill(l), kill(2), ptrace(2), sigblock(2), signal(2), sigpause(2), sigsetmask(2), sigspace(2), setjmp(3C), signal(5), 
termio(7). 
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NAME 

socket - create an endpoint for communication 

SYNOPSIS 

#include <sys/socket .h> 

AF_CCITT only: 

#include <x25/x2 5ccittproto.h> 

int socket (int af, int type, int protocol); 

DE SCREPTION 

socket ( ) creates an endpoint for communication and returns a descriptor. The socket descriptor 
returned is used in all subsequent socket-related system calls. 

The af parameter specifies an address family to be used to interpret addresses in later operations that 
specify the socket. These address families are defined in the include files <sys /socket .h> and 
<x2 5 /ccittproto . h>. The only currently-supported address families are: 

AP_INET (DARPA Internet addresses) 

AP_UNIX (path names on a local node) 

AF_CCITT (CCITTX.25 addresses) 

The type specifies the semantics of communication for the socket. Currently defined types are: 

SOCK_STREAM 

SOCK_DGRAM (for AFJNET only) 

A SOCK_STREAM type provides sequenced, reliable, two-way-connection-based byte streams. A 
S0CK_D6RAM socket supports datagrams (connectionless, unreliable messages of a fixed, typically small, 
maximum length). 

protocol specifies a particular protocol to be used with the socket. Normally, only a single protocol exists 
to support a particular socket type using a given address family. However, many protocols may exist, in 
which case a particular protocol must be specified. The protocol number to use depends on the communi- 
cation domain in which communication is to take place (see services(4) and protocols (4)). protocol can be 
supplied as zero, in which case the system chooses a protocol type to use. 

Sockets of type SOCK_STREAM are byte streams similar to pipes except that they are full-duplex instead 

of half-duplex. A stream socket must be in a connected state before any data can be sent or received on it. 

A connection to another socket is created with a connect ( ) or accept ( ) call. Once connected, data 

can be transferred using some variant of the send() and recv() or the read() and write ( ) m 

calls. When a session has been completed, a close () can be performed. I 

TCP, the communications protocol used to implement SOCK_STREAM for AFJNET sockets, ensures that 
data is not lost or duplicated. If a peer has buffer space for data and the data cannot be successfully 
transmitted within a reasonable length of time, the connection is considered broken and the next 
recv( ) call indicates an error with errno set to ETIMEDOUT. If SO_KEEPALIVE is set and the con- 
nection has been idle for two hours, the TCP protocol sends "keepalive" packets every 75 seconds to deter- 
mine whether the connection is active. These transmissions are not visible to users, and cannot be read 
by a recv ( ) call. If the remote system does not repond within 10 minutes (i.e., after 8 "keepalive" pack- 
ets have been sent), the next socket call (e.g., recv ( ) ) returns an error sets errno to ETIMEDOUT. A 
SIGPIPE signal is raised if a process sends on a broken stream; this causes naive processes that do not 
handle the signal to exit. An end-of-file condition (zero bytes read) is returned if a process tries to read on 
a broken stream. 

SOCK_DGRAM sockets allow sending of messages to correspondents named in send() calls. It is also 
possible to receive messages at such a socket with recv ( ) . 

The operation of sockets is controlled by socket level options set by the setsockopt () system call 
described by the getsockopt(2) manual entry. These options are defined in the file <sys /socket .h> 
and explained in the getsockopt(2) manual entry. 

2L25 only: 

Socket endpoints for communication over an X.25/9000 link can be in either address family AP_INET or 
AP_CCITT . If the socket is in the AP_INET family, the connection will behave as described above. TCP 
is used if the socket type is SOCK_STREAM; UDP is used if the socket type is SOCK_DGRAM. In both cases, 
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Internet Protocol (IP) and the X.25-to-IP interface module are used. If the socket is in the AP_CCITT 
address family, only the SOCK_STREAM socket type is supported. Refer to the topic Comparing X.25 Level 
3 Access to IP in the X.25 Programmer's Guide for more details on the difference between programmatic 
access to X.25 via IP and X.25 Level 3. 

If the socket is of the AP_CCITT family, the connection and all other operations pass data directly from 
the application to the X.25 Packet Level (level 3) without passing through a TCP or UDP protocol. Connec- 
tions of the AF_CCITT family cannot use most of the socket level options described in the getsockopt{2) 
manual entry. However, AF_CCITT connections can use many X.25-specific ioctl () calls, described by 
socketx25{l). 

DEPENDENCIES 
AFCCITT 

Only the SOCK_STREAM type is supported. 

RETURN VALUE 

Upon successful completion, socket ( ) returns a valid file descriptor referencing the socket. Otherwise, 
it returns -1 and sets errno to indicate the error. 

ERRORS 

socket ( ) fails if any of the following conditions are encountered: 

[EHOSTDOWN] The networking subsystem has not been started up. 

[EAFNOSUPPORT] The specified address family is not supported in this version of the system. 

[ESOCKTNOSUPPORT] The specified socket type is not supported in this address family. 

[EPROTONOSUPPORT] The specified protocol is not supported. 

[EMFILE] The per-process descriptor table is full. 

[ENOBUFS] No buffer space is available. The socket cannot be created. 

[ENFILE] The system's table of open files is temporarily full and no more socket ( ) calls 

can be accepted. 

[EPROTOTYPE] The type of socket and protocol do not match. 

[ETIMEDOUT] Connection timed-out. 

[EINVAL] SOCK_DGRAM sockets currently not supported for AFJJNIX address family. 

AUTHOR 

socket ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), recv(2), select(2), send(2), 
shutdown(2), af_ccitt(7F), socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P). 
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NAME 

socketpair - create a pair of connected sockets 

SYNOPSIS 

#include <sys/ socket ,h> 

int socketpair (int af, int type, int protocol, int sv[2]); 

DESCRIPTION 

socketpair ( ) creates an unnamed pair of connected sockets and returns two file descriptors in sv[0] 
and sv[l). The two sockets are indistinguishable, af specifies the address family. See socket(2). type 
specifies the semantics of communication for the socket, protocol specifies a particular protocol to be used. 
protocol can be supplied as zero, in which case the system chooses a protocol type to use. 

RETURN VALUES 

Upon successful completion, socketpair ( ) returns 0; otherwise, it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

socketpair ( ) fails if any of the following conditions are encountered: 

[EMFILE] The per-process file descriptor table is full. 

[ENFILE] The system file table is temporarily full. 

[EAFNOSUPPORT] The specified address family is not supported in this version of the system. 

[EPROTONOSUPPORT] The specified protocol is not supported in this version of the system. 

[EOPNOSUPPORT] The specified protocol does not support creation of socket pairs. 

DEFAULT] The sv parameter is not valid. 

[ENOBUFS] Insufficient resources were available in the system to perform the opera- 

tion. 

DEPENDENCIES 

This call is supported only for AP_UNIX. 

AUTHOR 

socketpair ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

read(2), write(2), socket(2). 
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NAME 

stat, lstat, fstat - get file status 

SYNOPSIS 

#include <sys/stat .h> 

int stat (const char *path / struct stat *buf); 
int lstat (const char *path, struct stat *buf); 
int fstat (int fildes, struct stat *buf); 

DESCRIPTION 

stat ( ) obtains information about the named file. 

path points to a path name naming a file. Read, write, or execute permission of the named file is not 
required, but all directories listed in the path name leading to the file must be searchable. 

Similarly, fstat ( ) obtains information about an open file known by the file descriptor fildes, obtained 
from a successful open( ) , creat ( ) , dup ( ) , f cntl ( ) , or pipe ( ) system call (see open{2), creat{2), 
dup(2\fcntl(2), orpipe(2)). 

lstat ( ) is similar to stat ( ) except when the named file is a symbolic link, in which case lstat ( ) 
returns the information about the link, while stat ( ) returns information about the file to which the link 
points. 

buf is a pointer to a stat ( ) structure into which information is placed concerning the file. 

The contents of structure stat ( ) pointed to by buf include the following members. Note that there is no 
necessary correlation between the placement in this list and the order in the structure. 



dev_t st_dev; 

ino_t st_ino; 

ushort st_fstype; 

ushort st_mode; 

ushort st_basemode 

ushort st_nllnk; 

uid_t st__uid; 

gid_t st_gid; 

dev_t st_rdev; 

off_t st_size; 

t ime_t s t_at ime ; 

t ime_t s t_mt ime ; 

t ime_t s t_c t ime ; 



uint st_acl:l; 



Field contents are as follows: 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



ID of device containing a */ 

directory entry for this file */ 

Inode number */ 

Type of filesystem this file */ 

is in; see vfsmount{2) */ 

Pile type, attributes, and */ 

access control summary */ 

Permission bits (see chmod{l)) *, 

Number of links */ 

User ID of file owner */ 

Group ID of file group */ 

Device ID; this entry defined */ 

only for char or blk spec files ' 

Pile size (bytes) */ 

Time of last access */ 

Last modification time */ 

Last file status change time */ 

Measured in sees since */ 

00:00:00 GMT, Jan 1, 1970 */ 



Set if 
access 



the file has 
control list 



optional 
entries " 



st_atime Time when file data was last accessed. Changed by the following system calls: 
creat ( ) , mknod ( ) , pipe ( ) , read ( ) , readv ( ) (see read(2)\ and ut ime ( ) . If a 
file is mapped into virtual memory, accesses of file data through the mapping may also 
modify st_mt ime. See mmap(2) . 

st_mtime Time when data was last modified. Changed by the following system calls: creat (), 
truncate ( ) , f truncate ( ) , (see truncate{2)), mknod ( ) , pipe ( ) , prealloc ( ) , 
ut ime ( ) , write ( ) , and writev ( ) (see write(2)). Also changed by close ( ) when 
the reference count reaches zero on a named pipe (FIFO special) file that contains data. 
If a file is mapped into virtual memory, updates of file data through the mapping may 
also modify st_mt ime. See mmap(2) . 
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st_ctime Time when file status was last changed. Changed by the following system calls: 
chmod(), chown(), creat(), fchmodO, fchown(), truncate (), f trun- 
cate (), (see truncate(2)\ link(), mknod(), pipe(), prealloc(), rename (), 
setacl (), unlink(),utime (), write ( ), andwritev( ) (see write(2)). 

The touch command (see touch(l) can be used to explicitly control the times of a file. 

st_mode The value returned in this field is the bit-wise inclusive OR of a value indicating the file's 
type, attribute bits, and a value summarizing its access permission. See mknod(2). 

For ordinary users, the least significant nine bits consist of the file's permission bits 
modified to reflect the access granted or denied to the caller by optional entries in the 
file's access control list. 

For users with appropriate privileges 

the least significant nine bits are the file's access permission bits. In addition, the 

S_IXUSR (execute by owner) mode bit is set if the following conditions are met: 

• The file is a regular file, 

• No permission execute bits are set, and 

• An execute bit is set in one or more of the file's optional access control fist 
entries. 

The write bit is not cleared for a file on a read-only file system or a shared-text program file that is 
being executed. However, get access ( ) clears this bit under these conditions (see getaccess(2). 

RETURN VALUE 

Upon successful completion, is returned. Otherwise, -1 is returned and errno is set to indicate the 
error. 

ERRORS 

stat() and lstat() fail if any of the following conditions are encountered: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist (for example, path is null or a component of path 

does not exist). 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] buf or path points to an invalid address. The reliable detection of this error is 

implementation dependent. 

[ELOOP] Too many symbolic finks were encountered in translating the path name. H 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

f stat ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid open file descriptor. 

[EFAULT] buf points to an invalid address. The reliable detection of this error is imple- 

mentation dependent. 

DEPENDENCIES 

HP Clustered Environment 

The contents of the stat() structure include the following additional members: 

cnode_t st_cnode; /* cnode ID of machine */ 

/* where the inode lives */ 
cnode_t st_rcnode /* cnode ID where this */ 

/* device file can be used */ 
dev_t st_realdev; /* Real device number of device */ 

/* containing the inode for this file */ 

st_dev The ID number for the volume on which the inode exists. This number may or may not 
be the device number for the device containing the volume. Device numbers are not 
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unique throughout a cluster, but the value of st_dev is guaranteed to be unique 
among all volumes currently mounted in the file system. The device number for the 
volume can always be found in the field st_realdev, which, together with st_cnode, 
fully specifies the device containing the volume. 

CD-ROM 

The st_uid and st_gid fields are set to -1 if they are not specified on the disk for a given file. 

NFS 

The st_basemode and st_acl fields are zero on files accessed remotely. 

WARNINGS 

Access Control Lists 

Access control fist descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS 
software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation 
for information about access control lists in the HP-UX BLS environment. 

AUTHOR 

stat() and fstat() were developed by AT&T, lstat ( ) was developed by the University of Califor- 
nia, Berkeley. 

SEE ALSO 

touch(l), chmod(2), chown(2), creat(2), link®, mknod(2), pipe(2), read(2), rename(2), setacl(2), time(2), trun- 
cate®, unlink(2), utime(2), write(2), acl(5), stat(5), privilege(5). 

STANDARDS CONFORMANCE 

stat ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 

f stat ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
lstat (): AES 
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f_bavall; 


/* 


long 


f_bfree; 


/* 


long 


f_b locks; 


/* 


long 


f_bslze; 


/* 


long 


f ffree; 


/* 


long 


f_files; 


/* 


long 


f_type; 


/* 


fsld t 


f_fsld 


/* 
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NAME 

statfs, fstatfs - get file system statistics 

SYNOPSIS 

#lnclude <sys/vfs.h> 

int statfs (const char *path, struct statfs *buf); 
lnt fstatfs (int fildes, struct statfs *buf); 

DESCRIPTION 

statfs ( ) returns information about a mounted file system, path is the path name of any file within the 
mounted file system. 

buf is a pointer to a statfs ( ) structure into which information is placed concerning the file system. The 
contents of the structure pointed to by buf include the following members: 

free blocks available to non-superuser */ 

free blocks */ 

total blocks in file system */ 

fundamental file system block size in bytes */ 

free file nodes in file system */ 

total file nodes in file system */ 

type of info, zero for now */ 

file system ID. f_fsid[l] is MOUNT_UFS, 

MOUNT_NFS, or MOUNT_CDPS */ 

A file node is a structure in the file system hierarchy that describes a file. For mounted HP-UX volumes, file 
node is an HP-UX inode. For other types of mounts, file node is defined by the system embodying the file 
pointed to bypath. 

Fields that are undefined for a particular file system are set to -1. 

fstatfs ( ) returns similar information about an open file referred to by file descriptor fildes. 

RETURN VALUE 

statfs () and fstatfs () return upon successful completion; otherwise, they return -1 and set 
errno to indicate the error. 

ERRORS 

statfs ( ) fails if any of the following conditions are encountered: 

[EACCES] Search permission is denied for a component of the path prefix. 

DEFAULT] buf or path points to an invalid address. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ELOOP] Too many symbolic links are encountered in translating the path name. 

[ENAMETOOLONG] A component of path exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is 
in effect, or path exceeds PATH_MAX bytes. 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

fstatfs ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid open file descriptor. 

[EFAULT] buf points to an invalid address. 

[EIO] An I/O error occurs while reading from or writing to the file system. 

AUTHOR 

statfs ( ) and fstatfs ( ) were developed by Sun Microsystems, Inc. 

SEE ALSO 

df(lM), stat(2), ustat(2). 
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NAME 

stime - set time and date 

SYNOPSIS 

#include <time.h> 

int stime (const time_t *tp); 

DESCRIPTION 

stime ( ) sets the system's idea of the time and date, tp points to the value of time as measured in seconds 
from 00:00:00 UTC (Coordinated Universal Time) January 1, 1970. 

RETURN VALUE 

Upon successful completion, stime () returns a value of 0; otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

[EPERM] st ime ( ) fails if the effective user ID of the calling process is not super-user. 

DEPENDENCIES 

HP Clustered Environment 

On systems that are members of a cluster, setting the time sets the time and date for all systems in 
the cluster. 

SEE ALSO 

date(l), gettimeofday(2), time(2). 

STANDARDS CONFORMANCE 

stime ( ) : SVID2, XPG2 
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NAME 

stty, gtty - control device 

SYNOPSIS 

#include <sgtty.h> 

int stty (int fildes, const struct sgttyb *argp); 
int gtty (int fildes, struct sgttyb *argp); 

REMARKS 

These system calls are preserved for backward compatibility with Bell Version 6. They provide as close an 
approximation as possible to the old Version 6 functions. All new code should use the TCSETA and 
TCGETA ioctl() calls described in termio(7). 

DESCRIPTION 

For certain status settings and status inquiries about terminal devices, the functions stty() and 
gtty ( ) are equivalent to 

ioctl (fildes, TIOCSETP, argp) 
and 

ioctl (fildes, TIOCGETP, argp) 
respectively; see termio(7). 

RETURN VALUE 

stty ( ) returns zero if the call was successful or -1 if the file descriptor does not refer to the kind of file for 
which it was intended. 

SEE ALSO 

stty(l), exec(2), sttyV6(7), tty(7), termio(7). 
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NAME 

swapon - add swap space for interleaved paging/swapping 

SYNOPSIS 

#include <unistd.h> 

int swapon ( 

const char *path, . . . 
/* [int min, 
int limit, 
int reserve, ] 
int priority */ 
); 

DESCRIPTION 

It path names a block device file: 

swapon ( ) makes it available to the system at the specified priority for allocation for paging and 
swapping. 

In this form, swapon ( ) takes only two arguments: the path to the block device file, and the priority. 

The device associated with path can be a device already known to the system, defined at system 
configuration time, or it can be a previously unspecified device. 

If the device was already defined at system configuration time and also has a start and/or size defined 
for that swap device, these values are used. 

Otherwise, if a filesystem exists on the device, swap is added following the filesystem, or if no filesys- 
tem exists, the complete device is used for swap. 

See the appropriate system administrator's manual for information on how the size of the swap area 
is calculated. 

It path names a directory: 

swapon ( ) makes the blocks on the file system rooted at path, available for paging and swapping. 

The min, limit, and reserve arguments are passed and used only if the path argument names a direc- 
tory. 

min indicates the number of file system blocks to take from the file system when swapon ( ) is 
called. 

limit indicates the maximum number of file system blocks the swap system is allowed to take from the 
file system. 

reserve indicates the number of file system blocks that are saved for file system use only. 

priority indicates the order in which the swap space from this device or file system is used. Space is taken 
from the lower-priority systems first. 

swapon ( ) can be used only by users who have appropriate privileges. 

ERRORS 

swapon ( ) fails if any of the following conditions are encountered: 

[EALREADY] The device or directory associated with path already has swap turned on. 

[ENXIO] The device associated with path could not be opened. 

[EBUSY] The device associated with path is already in use. 

[ENODEV] The device associated with, path does not exist. 

[EPERM] The effective user ID is not a user with appropriate privileges. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[ENOTBLK] The path argument is not a block special file or the root directory of a file sys- 

tem. 
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[ENOENT] 
[ENOSPC] 

[EINVAL] 

[ENOSYS] 
[EEXIST] 

[EIO] 

[EROFS] 

[EFAULT] 

[ENAMETOOLONG] 



The system-imposed limit on the number of swap file entries has been reached. 

There is is not enough available space on the specified file system or device. 

The node (see cluster(lM)) attempting to add swap had no swap configured at 
boot time. 

The device associated with path was specified at system configuration time to 
add swap following the file system, but no file system was found. 

The device associated with path was specified at system configuration time to 
add swap at a specified location, but that location is within an existing file sys- 
tem on the device. 

Unable to read the device associated with path. 

The device associated with path is read-only. 

The LIF header on the device associated with path contains inconsistent direc- 
tory data. 

The length of the specified path name exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
POSIX NO TRUNC is in effect. 



WARNINGS 

No means is available to stop swapping to a device. 

The system allocates no less than the amount specified in min. However, to make the most efficient use of 
space, more than the amount requested might be taken from the file system. The actual amount taken will 
not exceed the number of file system blocks indicated in reserve. 

Swapping to a file system is usually slower than swapping to a device. 

AUTHOR 

swapon ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

swapon(lM), privilege(5). 
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NAME 

symlink - make symbolic link to a file 

SYNOPSIS 

#include <symlink.h> 

int symlink (const char *namel, const char *name2); 

DESCRIPTION 

symlink( ) creates a file name2, which is a symbolic link to namel. Either name can be an arbitrary 
path name. The files need not be on the same file system. 

RETURN VALUE 

Upon successful completion, a zero value is returned. If an error occurs, the error code is stored in errno 
and a -1 value is returned. 

ERRORS 

The symbolic link is made unless one or more of the following is true: 



[ENOTDIR] 
[ENAMETOOLONG] 

[ENOENT] 

[EACCESJ 

[EDQUOT] 

[ELOOP] 

[EEXIST] 

IEIO] 

[EROFS] 
[ENOSPC] 

[ENOSPC] 

[ENOSPC] 

[EIO] 
[EFAULT] 



A component of the name2 prefix is not a directory. 

A component of either path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect, or the entire length of either path name 
exceeds PATH_MAX bytes. 

A component of the name2 prefix does not exist. 

A component of the name2 path prefix denies search permission. 

User's disk quota block or inode limit has been reached for this file system. 

Too many symbolic links were encountered in translating the path name. 

name2 already exists. 

An I/O error occurred while making the directory entry for name2 , allocating the 
inode for name2, or writing out the link contents of name2. 

The file name.2 resides on a read-only file system. 

The directory in which the entry for the new symbolic link is being placed can- 
not be extended because there is no space left on the file system containing the 
directory. 

The new symbolic link cannot be created because there is no space left on the 
file system that will contain the symbolic link. 

There are no free inodes on the file system on which the symbolic link is being 
created. 

An I/O error occurred while making the directory entry or allocating the inode. 

namel or name2 points outside the process' allocated address space. The reli- 
able detection of this error is implementation dependent. 



AUTHOR 

syml ink ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

cp(l), link(2), readlink(2), unlink(2), symlink(4). 

STANDARDS CONFORMANCE 

symlink():AES 
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NAME 

sync, lsync - update super-block 

SYNOPSIS 

^include <unistd.h> 

void sync (void) ; 
void lsync (void) ; 

DESCRIPTION 

sync ( ) causes all information in memory that should be on disk to be written out. This includes modified 
super blocks, modified inodes, and delayed block I/O. 

It should be used by commands and programs that examine a file system, such as f sck, df , etc. It is man- 
datory before a shutdown. 

The writing, although scheduled, is not necessarily complete upon return from sync. 

In some HP-UX systems, sync ( ) may be reduced to a no-op. This is permissible on a system which does 
not cache buffers, or in a system that in some way ensures that the disks are always in a consistent state. 

In the HP Clustered Environment, sync ( ) causes updates of all file systems in the cluster to be written 
out, while lsync ( ) performs only a local sync ( ) ; that is, local buffers are flushed to disk and to remote 
nodes of the cluster, but remote nodes do not flush their own pages. 

AUTHOR 

sync ( ) was developed by HP and AT&T Bell Laboratories, lsync ( ) was developed by HP. 

SEE ALSO 

sync(lM), fsync(2). 

STANDARDS CONFORMANCE 

sync ( ) : SVID2, XPG2 
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NAME 

sysconf - get configurable system variables 

SYNOPSIS 

#include <unistd.h> 

long sysconf (int name); 

Int CPU_IS_PA_RISC (long cpuvers) ; 

int CPU_IS_HP_MC68K(long cpuvers); 

DESCRIPTION 

sysconf ( ) provides a way for applications to determine the current value of a configurable limit or vari- 
able. 

The name argument represents the system variable being queried. 

The following table fists the configuration variables whose values can be determined by calling sys- 
conf ( ) , and for each variable, the associated value of the name argument and the value returned: 

Variable Value of name Value Returned 



AES_OS_VERSION 
ARG_MAX 

ATEXIT_MAX 
BC_BASE_MAX 

BC_DIM_MAX 
BC_SCALE_MAX 

BC_STRING_MAX 

CHILD_MAX 

CLK_TCK 

CLOCKS_PER_SEC 

COLL_WEIGHTS_MAX 

CPU_VERSION 
EXPR_NEST_MAX 

IO_TYPE 

LINE_MAX 



_SC_AES_OS_VERSION 
_SC_ARG_MAX 

_SC_ATEXIT_MAX 
_SC_BC_BASE_MAX 

_SC_BC_DIM_MAX 
_SC_BC_SCALE_MAX 

_SC_BC_STRING_MAX 
_SC_CHILD_MAX 
_SC_CLK_TCK 
_SC_CLOCKS_PER_SEC 
_SC COLL_WEIGHTS_MAX 



_SC_CPU_VERSION 
_SC_EXPR_NEST_MAX 

_SC_IO_TYPE 

_SC LINE_MAX 



Version number of OSF/AES OSC supported 

Maximum total length of the arguments for 
exec ( ) in bytes, including environment data 
(see exec(2)) 

Maximum number of functions that can be 
registered with atexlt() (see atexit(2)) 

Maximum ibase (input number radix) and 
obase (output number radix) allowed by be 
(see 6c(l)) 

Maximum number of elements in an array 
permitted by be (see 6c(l)) 

Maximum scale factor (number of digits to the 
right of the decimal point) allowed by be (see 
bc(l)) 

Maximum length of strings allowed by be 
(see 6c(l)) 

Maximum number of simultaneous processes 
per user ID (see fork{2)) 

Number of clock intervals per second for 
times ( ) (see times{2)) 

Number of clock ticks per second for 
clock ( ) (see clock(SC)) 

Maximum number of weights that can be 
assigned to an entry of the LC_COLLATE 
order keyword in a localedef input file 
(see localedefilM)) 

Version of CPU architecture (see below) 

Maximum parenthesis nesting level for expr 
expressions (see expr(l)) 

Type of I/O drivers the kernel supports (see 
below) 

Maximum number of bytes in an input fine 
(including the newline) for POSIX.2 utilities 
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NOROUPS MAX 



OPEN MAX 



PAGE_SIZE 
PASS MAX 



?os: 



SEt J. J 



POSIX_SAVED_IDS 
POSIX_VERSION 

POSIX2_C_BIND 
POSIX2 C DEV 



_SC_NOROUPS_MAX 

_SC_OPEN_MAX 

_SC_PAOE_SIZE 
_SC_PASS_MAX 

SC JOB CONTROL 

_SC_SAVED_IDS 

_SC VERSION 



SC 2 C BIND 



SC 2 C DEV 



POSIX2_C_VERSION _SC_2_C_VERSION 

POSIX2_FORT_DEV _SC_2_FORT_DEV 

POSIX2_FORT_RUN _SC_2_FORT_RUN 

POSIX2_LOCALEDEF _SC_2_LOCALEDEF 

POSIX2_SW_DEV _SC_2_SW_DEV 

POSIX2_UPE _SC_2_UPE 

POSIX2_VERSION _SC_2_VERSION 

RE_DUP_MAX _SC_RE_DUP_MAX 



SECURITY_CLASS _SC_SECURITY_CLASS 

STREAM_MAX SC STREAM MAX 



TZNAME MAX 



SC TZNAME MAX 



Maximum number of simultaneous supple- 
mentary group IDs per process 

Maximum number of files that one process can 
have open at one time 

Kernel memory page size 

Maximum number of significant bytes in a 
password 

Positive if the system supports POSIX job con- 
trol; -1 otherwise 

Positive if each process has a saved set-user- 
ID and a saved set-group-ID; -1 otherwise 

Approval date of the POSDC.l Standard (such 
as 199009 for POSIX. 1-1990) to which the system 
conforms. This value indicates the year (first four 
digits) and month (next two digits) that the standard 
was approved by the IEEE Standards Board. 

Equal to 1 if the POSDC.2 C Language Bind- 
ings Option is available through the c 8 9 util- 
ity; -1 otherwise 

Equal to 1 if the POSIX.2 C Language 
Development Utilities Option is supported; -1 
otherwise 

Current version of the POSIX.2 C Language 
Binding Option supported (same format as 
_POSIX_VERSION); -1 otherwise. 

Equal to 1 if the POSIX.2 FORTRAN Develop- 
ment Utilities Option is supported; -1 other- 
wise 

Equal to 1 if the POSIX.2 Fortran Runtime 
Utilities Option is supported; -1 otherwise 

Equal to 1 if locales can be created with the 
POSDC.2 localedef utility; -1 otherwise 

Equal to 1 if the POSDC.2 Software Develop- 
ment Utilities Option is supported; -1 other- 
wise 

Equal to 1 if the POSIX.2 User Portability 
Utilities Option is supported; -1 otherwise 

Current version of POSIX.2 (same format as 
_POSIX_VERSION) 

Maximum number of repeated occurrences of 
a regular expression permitted when using 
the interval notation \{m,re\} (see 
regcomp(3C)) 

DoD security level (see below) 

Maximum number of stdio streams that one 
process can have open at one time 

Maximum number of bytes in a timezone 
name for the TZ environment variable 
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XOPEN_CRYPT _SC_XOPEN_CRYPT Equal to 1 if the X/Open Encryption Feature 

Group is supported; -1 otherwise 

X0PEN_ENH_I18N _SC_X0PEN_ENH_I18N Equal to 1 if the X/Open Enhanced Interna- 

tionalization Feature Group is supported; -1 
otherwise 

XOPEN_SKM _sc_xofen_skm Equal to I if the X/Open Shared Memory 

Feature Group is supported; -1 otherwise 

XOPEN_VERSlON _sc_XOPEN_VERSION Issue number of XI Open Portability Guide 

supported 

Some of the variables in the table are defined as constants in <limits . h> (see limits(5)). The associated 
values of the name argument are defined in <unistd .h>. 

The SECURITY_CLASS variable (returned by sysconf (_SC_SECURITY__CLASS)) can have the fol- 
lowing possible values with meanings as indicated: 

Value Meaning 

SEC_CLASS_NONE No DoD security level supported 

SEC_class_c2 DoD C2 level security 

SEC_CLASS_B1 DoD Bl level security 

The possible values of the IO_TYPE variable (returned by sysconf (_SC_IO_TYPE) ) and their mean- 
ings are: 

Value Meaning 

lo_TYPE_WSlO Workstation I/O (used by Series 300/400/700) 

I0_TYPE_SI0 Server I/O (used by Series 800) 

Since the Series 700 instruction set is compatible with Series 800 but its I/O system differs, IO_TYPE can 
be used to detect which I/O system is present in a single executable program that can be run on either a 
Series 700 or a Series 800. 

The possible values of the CPU_VERSION variable (returned by sysconf (_SC_CPU_VERSION)) and 
their meanings are: 

Value Meaning 

CPU_PA_RISC1_0 HP Precision Architecture RISC Version 1.0 
CPU_PA_RISC1_1 HP Precision Architecture RISC Version 1.1 

CPU_HP_MC68020 Motorola MC68020 
CPU_HP_MC68030 Motorola MC68030 
CPU_HP_MC68040 Motorola MC68040 

The CPU_IS_PA_RISC() and CPU_IS_HP_MC68K( ) functions classify cpuvers, a value of the 
CPU_VERSION variable, as to its processor family. 

RETURN VALUE 

Upon successful completion, sysconf () returns the value of the named variable. If the value of name is 
not valid, sysconf ( ) returns -1 and sets errno to indicate the error. If the variable corresponding to 
name is not defined, sysconf ( ) returns -1, but does not change errno. 

CPU_IS_PA_RISC ( ) returns positive non-zero if cpuvers is an HP PA-RISC processor; zero if not. 

CPU_IS_HP_MC68K ( ) returns positive non-zero if cpuvers is a "Motorola MC680xO" processor; zero if not. 

ERRORS 

sysconf ( ) fails if: 

[EINVAL] The value of name is not valid. 

EXAMPLES 

The following example determines the number of times the system clock ticks each second: 
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#include <unistd.h> 
long ticks; 

ticks = sysconf (_SC_CLK_TCK) ; 
The following example determines whether the current processor is an HP PA-RISC machine: 
ttinclude <unistd.h> 
if (CPU_IS_PA_RISC (sysconf (_SC_CPU_VERSION) ) ) 

WARNINGS 

CPU_IS_PA_RISC() and CPU_IS_HP_MC68K( ) are implemented as macros. 

Normally, the values returned from sysconf ( ) do not change during the lifetime of the calling process. 
However, the value of the symbolic constant _POSIX_VERSION and thus the value of 
sysconf (_SC_VERSION) can vary under certain circumstances. If either of the feature test macros 
_P0SIX1_1988 or _XPG3 is defined by the programmer prior to including <unistd.h>, the value of 
_POSIX_VERSION is denned as 198808, in conformance with POSIX.1-1988, FIPS 151-1, and XPG3. Oth- 
erwise, the value of _POSIX_VERSIONis defined as 199009, in conformance withPOSK.1-1990. 

Similarly, the value of the symbolic constant _XOPEN_VERSION and thus the value of 
sysconf (_SC_XOPEN_VERSION) can vary under certain circumstances. If the feature test macro 
_XPG3 is defined by the programmer prior to including <unistd .h>, the value of _XOPEN_VERSION is 
defined as 3, in conformance with XPG3. Otherwise, the value of _XOPEN_VERSION is defined as 4, in 
conformance with XPG4. 

See stdsyms(5) for more information about these feature test macros. 

AUTHOR 

sysconf ( ) was developed by HP and POSDC 

CPU_IS_PA_RISC() and CPU_IS_HP_MC68K( ) were developed by HP. 

SEE ALSO 

getconfQ), atexit(2), exec(2), fork(2), getrlimit(2), pathconf(2), times(2), clock(3C), regcomp(3C), limits(5), 
stdsyms(5), unistd(5), x_open(5). 

STANDARDS CONFORMANCE 

sysconf ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, POSIX.2 



HP-UX Release 9.0: August 1992 - 4 - 249 



time (2) time(2) 



NAME 

time - get time 

SYNOPSIS 

#include <time.h> 

time_t time(time_t *tloc); 

DESCRIPTION 

time ( ) returns the value of time in seconds since the Epoch. 

If tloc is not a null pointer, the return value is also assigned to the object to which it points. 

RETURN VALUE 

Upon successful completion, time() returns the value of time. Otherwise, a value of (time_t)-l is 
returned and errno is set to indicate the error. 

ERRORS 

[EFAULT] time () fails if tloc points to an illegal address. The reliable detection of this error is 

implementation dependent. 

SEE ALSO 

date(l), gettimeofday(2), stime(2), ctime(3C), strftime(3C). 

STANDARDS CONFORMANCE 

time ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l, ANSI C 
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NAME 

times - get process and child process times 

SYNOPSIS 

ttinclude <sys/times.h> 

clock_t times(struct tins *buffer); 

DESCRIPTION 

times ( ) fills the structure pointed to by buffer with time-accounting information. The structure defined 
in <sys /times .h> is as follows: 



struct tms { 








clock_t 


tms_utime; 


/* 


user time */ 


clock._t 


tms_stime; 


/* 


system time */" 


clock_t 


tms_cutime; 


/* 


user time, children */ 


clock t 
}; 


tms_cstime; 


/* 


system time, children */ 



This information comes from the calling process and each of its terminated child processes for which it has 
executed a wait ( ) , wait3 ( ) , or waitpid( ) . The times are in units of 1/CLK_TCK seconds, where 
CLK_TCK is processor dependent The value of CLK_TCK can be queried using the sysconf ( ) function 
(see sysconf(2)). 

tms_ut ime is the CPU time used while executing instructions in the user space of the calling process. 

tms_st ime is the CPU time used by the system on behalf of the calling process. 

tms_cut ime is the sum of the tms_ut imes and tms_cut imes of the child processes. 

tms_cstime is the sum of the tms_stimes and tms_cst imes of the child processes. 

RETURN VALUE 

Upon successful completion, times ( ) returns the elapsed real time, in units ofl/CLK_TCK of a second, 
since an arbitrary point in the past (such as system start-up time). This point does not change from one 
invocation of times ( ) to another. If times ( ) fails, -1 is returned and errno is set to indicate the 
error. 

ERRORS 

[EFAULT] times ( ) fails if buffer points to an illegal address. The reliable detection of this error is 

implementation dependent. 

SEE ALSO 

time(l), gettimeofday(2), exec(2), fork(2), sysconf(2), time(2), wait(2). 

WARNINGS 

Not all CPU time expended by system processes on behalf of a user process is counted in the system CPU 
time for that process. 

STANDARDS CONFORMANCE 

times () : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

truncate, ftruncate - truncate a file to a specified length 

SYNOPSIS 

#include <unistd.h> 

int truncate (const char *path, size_t length); 
int ftruncate(int fildes, size_t length); 

DESCRIPTION 

truncate ( ) causes the file named by path or referenced by fd to have a size of length bytes. If the file 
previously was larger than this size, the extra data is lost. If it was previously shorter, bytes between the 
old and new lengths are read as zeroes. With ftruncate ( ) , the file must be open for writing; for trun- 
cate ( ) the user must have write permission for the file. 

RETURN VALUES 

truncate ( ) returns a value of if successful; otherwise a -1 is returned, and errno is set to indicate 
the error. 

ERRORS 

truncate ( ) fails if any of the following conditions are encountered: 

[ENOTDIR] A component of the path prefix of path is not a directory. 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] Write permission is denied on the file. 

[EENVAL] length was greater than the maximum file size. 

[EISDIR] The named file is a directory. 

[EROFS] The named file resides on a read-only file system. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being executed. 

[EFAULT] path points outside the process's allocated address space. The reliable detection of 
this error is implementation dependent. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[EDQUOT] User's disk quota block limit has been reached for this file system. 

ftruncate ( ) fails if any of the following conditions are encountered: 

[EBADF] fd is not a valid file descriptor. 

[EINVAL] fd references a file that was opened without write permission. 

[EDQUOT] User's disk quota block limit has been reached for this file system. 

AUTHOR 

truncate ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

open(2). 

STANDARDS CONFORMANCE 

truncate ( ) : AES 

ftruncate ():AES 
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NAME 

ulimit - get and set user limits 

SYNOPSIS 

#inc lude <ul lmit . h> 

long ulimit (int cmd, . . . ) ; 

DESCRIPTION 

ulimit ( ) provides for control over process limits. Available values for cmd are: 

UL_GETFS IZE Get the file size limit of the process. The limit is in units of 5 12-byte blocks and 

is inherited by child processes. Files of any size can be read. The optional 
second argument is not used. 

UL_SETFSIZE Set the file size limit of the process to the value of the optional second argument 

which is taken as a long. Any process can decrease this limit, but only a process 
with an effective user ID of super-user can increase the limit. Note that the limit 
must be specified in units of 5 12-byte blocks. 

UL_GETMAXBRK Get the maximum possible break value (see brk{2)). Depending on system 
resources such as swap space, this maximum might not be attainable at a given 
time. The optional second argument is not used. 

ERRORS 

ulimit ( ) fails if one or more of the following conditions is true. 

[EINVAL] cmd is not in the correct range. 

[EPERM] ulimit () fails and the limit is unchanged if a process with an effective user ID 

other than super-user attempts to increase its file size limit. 

RETURN VALUE 

Upon successful completion, a non-negative value is returned. Errors return a -1, with erxno set to indi- 
cate the error. 

SEE ALSO 

brk(2), write(2). 

STANDARDS CONFORMANCE 

ulimit ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

umask - set and get file creation mask 

SYNOPSIS 

#include <sys/stat.h> 

mode_t umask(mode_t cmask); 

DESCRIPTION 

umask ( ) sets the process's file mode creation mask to umask ( ) and returns the previous value of the 
mask. Only the file access permission bits of the masks are used. 

The bits set in cmask specify which permission bits to turn off in the mode of the created file, and should be 
specified using the symbolic values defined in stat (5). 

EXAMPLES 

The following creates a file named path in the current directory with permissions 
S_IRWXU I S_IR6RP I S_IXGRP, so that the file can be written only by its owner, and can be read or exe- 
cuted only by the owner or processes with group permission, even though group write permission and all 
permissions for others are passed in to creat ( ) . 

ttinclude <sys/types.h> 
#include <sys/stat.h> 

int fildes; 

(void) umask ( S_IWGRP | S_IRWXO ) ; 

fildes = creat ("path", S_IRWXU|S_IRWX6|S_IRWX0) ; 

RETURN VALUE 

The previous value of the file mode creation mask is returned. 

SEE ALSO 

mkdir(l), sh(l), mknod(lM), chmod(2), creat(2), mknod(2), open(2). 

STANDARDS CONFORMANCE 

umask( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

umount - unmount a file system 

SYNOPSIS 

#include <sys /mount. h> 

int umount (const char *name) ; 

DESCRIPTION 

umount ( ) requests that a previously mounted file system contained on the block special device identified 
by name be unmounted, name is a pointer to a path name. After unmounting the file system, the directory 
upon which the file system was mounted reverts to its ordinary interpretation. 

umount ( ) can also request that a file system mounted previously on the directory identified by name be 
unmounted. After unmounting the file system, name reverts to its ordinary interpretation. 

umount ( ) can be invoked only by the user with the appropriate privilege. 

NETWORKING FEATURES 

NFS 
path must indicate a directory name when unmounting an NFS file system. 

RETURN VALUE 

If successful, umount ( ) returns a value of 0. Otherwise, it returns a value of -1 and sets errno to 
indicate the error. 

ERRORS 

umount ( ) fails if one or more of the following are true: 

[EPERM] The effective user ID of the process is not that of a user with appropriate privileges. 

[ENOENT] name does not exist. 

[ENOTBLK] name is not a block special device. 

[EINVAL] name is not mounted. 

[EBUSY] A file on name is busy. 

[EFAULT] name points outside the allocated address space of the process. Reliable detection of this 

error is implementation dependent. 

[ENXIO] The device associated with name does not exist. 

[ENOTDIR] A component of name is not a directory. 

[ENOENT] name is null. 

[ENAMETOOLONG] 

name exceeds PATH_MAX bytes, or a component of name exceeds NAME_MAX bytes while 
_POS IX_NO_TRUNC is in effect. 

[EACCES] A component of the path prefix of name denies search permission. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

WARNINGS 

If umount ( ) is called from the program level (that is, not from the mount(1M) level), the table of mounted 
devices contained in /etc/mnttab is not updated automatically. Updating of /etc/mnttab is per- 
formed by the mount and syncer commands (see mount (1M) and syncer(lM) for more information). 

DEPENDENCIES 

HP Clustered Environment: 

When umount ( ) is called from a client node and path refers to a directory on which is mounted a 
UFS file system (as opposed to an NFS file system; see vfsmount(2)\ an EINVAL error is returned. This 
behavior is subject to change in future releases, and its use in applications is not recommended. 

SEE ALSO 

mount(lM), syncer(lM), mount(2), vfsmount(2). 
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STANDARDS CONFORMANCE 

umount ( ) : SVID2, XPG2 
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NAME 

uname, setuname - get/set name of current HP-UX system 

SYNOPSIS 

#include <sys/utsname.h> 

int uname (struct utsname *name); 

int setuname (const char *name, size_t namelen) ; 

DESCRIPTION 

uname ( ) stores information identifying the current HP-UX system in the structure pointed to by name . 

uname ( ) uses the structure defined in <sys /utsname .h> whose members are: 

#define UTSLEN 9 
#define SNLEN 15 

char sysname [UTSLEN] ; 
char nodename [UTSLEN] ; 
char release [UTSLEN] ; 
char version [UTSLEN] ; 
char machine [UTSLEN] ; 
char ldnumber [SNLEN] ; 

uname () returns a null-terminated string in each field. The sysname field contains HP-UX. Similarly, 
the nodename field contains the name by which the system is known on a communications network. The 
release field contains the release number of the operating system, such as 8 . or 8 . .1. The ver- 
sion field contains additional information about the operating system. The first character of the ver- 
sion field is set to: 



Character 


Series 700/800 




Series 300/400 


A 


two-user system 




two-user system 


B 


16-user system 




unlimited-users system 


C 


32-user system 






D 


64-user system 






E 


8-user system 






U 


unlimited-users 


system 





(Note that the contents of the version field might change on future releases as AT&T license agreement res- 
trictions change.) The machine field contains a standard name that identifies the hardware on which the 
HP-UX system is running. The ldnumber is a unique identification number within that class of 
hardware, possibly a hardware or software serial number. This field returns the null string to indicate the 
lack of an identification number. 

setuname () sets the nodename field in the utsname structure to name, which has a length of I 

namelen characters. This is usually executed by /etc /re at system boot time. Names are limited to I 

UTSLEN - 1 characters; UTSLEN is defined in <sys /utsname .h>. 

ERRORS 

[EPERM] setuname ( ) was attempted by a user lacking the appropriate privileges. 

[EFAULT] name points to an illegal address. The reliable detection of this error is implementation 

dependent. 

RETURN VALUE 

Upon successful completion, a non-negative value is returned. Otherwise, -1 is returned and errno is set 
to indicate the error. 

AUTHOR 

uname ( ) was developed by AT&T and HP. 

SEE ALSO 

hostname(l), uname(l), gethostname(2), sethostname(2), privilege(5). 

STANDARDS CONFORMANCE 

uname ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

unlink - remove directory entry; delete file 

SYNOPSIS 

ttinclude <unistd.h> 

int unlink (const char *path) ; 

DESCRIPTION 

unlink ( ) removes the directory entry named by the path name pointed to bypath. 

When all links to a file have been removed and no process has the file open, the space occupied by the file is 
freed and the file ceases to exist. If one or more processes have the file open when the last link is removed, 
only the directory entry is removed immediately so that processes that do not already have the file open 
cannot access the file. After all processes close their references to the file, if there are no more links to the 
file, the space occupied by the file is then freed and the file ceases to exist. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

The named file is unlinked unless one or more of the following are true: 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the link to be removed. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist (for example, path is null or a component of path does not 

exist). 

[EPERM] The named file is a directory and the effective user ID of the process is not a user with 

appropriate privileges. 

[EBUSY] The entry to be unlinked is the mount point for a mounted file system. 

[ETXTBSY] The entry to be unlinked is the last link to a pure procedure (shared text) file that is being 

executed. 

[EROFS] The directory entry to be unlinked is part of a read-only file system. 

[EFAULT] path points outside the process's allocated address space. The reliable detection of this 

error is implementation dependent. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a com- 
ponent of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in 
effect. 

[ELOOP] Too many symbolic finks were encountered in translating the path name. 

WARNINGS 

If unlink ( ) is used on a directory that is not empty (contains files other than . and . . ), the directory is 
unlinked, the files become orphans, and the directory fink count is left with an inaccurate value unless they 
are linked by some other directory. 

If unlink () is used on a directory that is empty (contains only the files . and . .), the directory is 
unlinked, but the parent directory's link count is left with an inaccurate value. 

In either of the above cases, the file system should be checked using f sck (see fsck(lM)). To avoid these 
types of problems, use rmdir() instead (see rmdir{2)). 

SEE ALSO 

rm(l), close(2), link(2), open(2), rmdir(2), privileged). 

STANDARDS CONFORMANCE 

unlink ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

ustat - get file system statistics 

SYNOPSIS 

#inc lu.de <ustat.h> 

int ustat (dev_t dev, struct ustat *buf); 

DESCRIPTION 

ustat ( ) returns information about a mounted file system, dev is a device number identifying a device 
containing a mounted file system, huf is a pointer to a ustat structure (defined in <ustat .h>) that 
includes the following elements: 

/* Total free blocks */ 

/* Number of free lnodes */ 

/* Fllsys name */ 

/* Fllsys pack name */ 

/* Block size */ 

The values of the f _tf ree and f _blksize fields are reported in fragment size units. 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

ustat ( ) fails if one or more of the following is true: 

[EINVAL] dev is not the device number of a device containing a mounted file system. 

[EFAULT] buf points outside the process's allocated address space. The reliable detection of this error 

is implementation dependent. 

AUTHOR 

us tat ( ) was developed by AT&T and HP. 

SEE ALSO 

touch(l), stat(2), fs(4). 

STANDARDS CONFORMANCE 

ustat ( ) : SVID2, XPG2 



daddr_t 


f_tfree; 


ino_t 


f_tinode; 


char 


f _f name [ 6 ] ; 


char 


f_fpack[6] ; 


int 


f_blksize; 
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NAME 

utime - set file access and modification times 

SYNOPSIS 

#include <utime.h> 

int utime (const char *path, const struct utimbuf *times) ; 

DESCRIPTION 

utime ( ) sets the access and modification times of the file to which the path argument refers. 

If times is a null pointer, the access and modification times of the file are set to the current time. A process 
must be the owner of the file or have write permission on the file to use utime ( ) in this manner. 

If times is not a null pointer, times is interpreted as a pointer to a utimbuf structure and the access and 
modification times are set to the values contained in the designated structure. Only the owner of the file or 
users having appropriate privileges can use ut ime ( ) this way. 

The following times in the ut imbuf structure defined in <ut ime . h> are measured in seconds since 
00:00:00 UTC (Universal Coordinated Time), Jan. 1, 1970. 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

utime ( ) fails if one or more of the following is true: 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EACCES] Search permission is denied by a component of the path prefix. 

[EPERM] The effective user ID is not a user with appropriate privileges, and not the owner of 

the file, and times is not a null pointer. 

[EACCES] The effective user ID is not a user with appropriate privileges, and not the owner of 

the file, times is a null pointer, and write access is denied. 

[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] times is not a null pointer, and points outside the process's allocated address space. 

The reliable detection of this error is implementation dependent. 

[EFAULT] path points outside the process's allocated address space. The reliable detection of 

this error is implementation dependent. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

DEPENDENCIES 

NFS: utime() may return EPERM when invoked on a remote file owned by the super-user, even if the 
invoking user has write permission on the file. 

SEE ALSO 

touch(l), stat(2). 

STANDARDS CONFORMANCE 

utime ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

vfork - spawn new process; share virtual memory 

SYNOPSIS 

ttinclude <unistd.h> 

pld_t vfork(void); 

REMARKS 

vfork ( ) is a higher performance version of f ork( ) that is provided on some systems where a perfor- 
mance advantage can be attained. 

vfork ( ) differs from fork ( ) only in that the child process can share code and data with the calling pro- 
cess (parent process). This speeds cloning activity significantly at a risk to the integrity of the parent pro- 
cess if vfork ( ) is misused. 

The use of vfork ( ) for any purpose except as a prelude to an immediate exec ( ) or exit ( ) is not 
supported. Any program that relies upon the differences between fork ( ) and vfork ( ) is not portable 
across HP-UX systems. 

All HP-UX implementations must provide the entry vf ork ( ) , but it is permissible for them to treat it 
identically to fork. On some implementations the two are not distinguished because the f ork( ) imple- 
mentation is as efficient as possible. Other versions may do the same to avoid the overhead of supporting 
two similar calls. 

DESCRIPTION 

vfork ( ) can be used to create new processes without fully copying the address space of the old process. If 
a forked process is simply going to do an exec ( ) (see erec(2)), the data space copied from the parent to the 
child by fork ( ) is not used. This is particularly inefficient in a paged environment, making vfork is 
particularly useful. Depending upon the size of the parent's data space, vfork ( ) can give a significant 
performance improvement over fork ( ) . 

vfork ( ) differs from fork ( ) in that the child borrows the parent's memory and thread of control until a 
call to exec ( ) or an exit (either by a call to exit ( ) or abnormally (see exec(2) and exit{2)). The parent 
process is suspended while the child is using its resources. 

vfork ( ) returns in the child's context and (later) the pid of the child in the parent's context. 

vf ork( ) can normally be used just like f ork( ) . It does not work, however, to return while running in 
the child's context from the procedure which called vfork ( ) since the eventual return from vfork ( ) 
would then return to a no longer existent stack frame. Be careful, also, to call _exit ( ) rather than 
exit ( ) if you cannot exec ( ) , since exit ( ) flushes and closes standard I/O channels, thereby damag- 
ing the parent process's standard I/O data structures. (Even with f ork( ) it is wrong to call exit () 
since buffered data would then be flushed twice.) 

The [vfork, exec] window begins at the vf ork( ) call and ends when the child completes its exec ( ) 
call. 

RETURN VALUE 

Upon successful completion, vfork ( ) returns a value of to the child process and returns the process ID 
of the child process to the parent process. Otherwise, a value of -1 is returned to the parent, no child pro- 
cess is created, and errno is set to indicate the error. 

ERRORS 

vfork ( ) fails and no child process is created if any of the following conditions are encountered: 

[EAGAIN] The system-wide limit on the total number of processes under execution would be 

exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes under execution by a sin- 

gle user would be exceeded. 

DEPENDENCIES 
Series 800 

Process times for the parent and child processes within the [vf ork,exec] window may be inaccurate. 

Parent and child processes share the same stack space within the [vf ork,exec] window. If the size 
of the stack has been changed within this window by the child process (return from or call to a 
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function, for example), it is likely that the parent and child processes will be killed with signal SIG- 
SEGVorSIGBUS. 

In the [vf ork,exec] window, a call to signal ( ) (see signal(2) that installs a catching function 
can affect handling of the signal by the parent. The parent is not affected if the handling is being set 
to SIG_DFL or SIG_IGN, or if either sigactionO or sigvectorO is used (see sigaction(2) 
grwl si a vBctor^2^. 

AUTHOR 

vf ork( ) was developed by the University of California, Berkeley. 

SEE ALSO 

exec(2), exit(2), fork(2), wait(2). 
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NAME 

vfsmount - mount a file system 

SYNOPSIS 

# include < sys /mount .h> 

int vfsmount ( 

int type , 

const char *dir, 

int flags, 

caddr_t data 
); 

DESCRIPTION 

vfsmount ( ) attaches a file system to a directory. After a successful return, references to directory dir 
refer to the root directory of the newly mounted file system, dir is a pointer to a null-terminated string con- 
taining a path name, dir must exist already, and must be a directory, dir cannot be a context-dependent 
file (see cdf(4)). Its old contents are inaccessible while the file system is mounted, vfsmount ( ) differs 
from mount ( ) (see mount(2)) in its ability to mount file system types other than just the UFS type. 

type indicates the type of the file system. It must be one of the types described below, vfsmount ( ) does 
not check that the file system is actually of type type; if type is incorrect, vfsmount ( ) may cause the pro- 
cess to hang. To prevent such problems, statfsdevO (see statfsdev (3c)) should be called before 
vf smount ( ) to check the file system type, which stat f sdev ( ) places in the f _f s id [ 1 ] field of the 
statf s structure it returns. 

The flags argument determines whether the file system can be written to (functionally identical to the 
rwf lag argument in mount(2) in this regard). It also controls whether programs from the mounted file 
system are allowed to have set-uid execution. Physically write-protected and magnetic tape file systems 
must be mounted read-only. Failure to do so results in a return of -1 by vfsmount ( ) and a value of EIO 
in er rno. The following values for the flags argument are defined in <sys /mount . h>: 

M_RDONLY Mount done as read-only. 

M_NOSUID Execution of set-uid programs not permitted. 

data is a pointer to a structure containing arguments specific to the value contained in type. The follow- 
ing values for types are defined in <sys /mount . h>: 

MOUNT_UFS Mount a local HFS file system, data points to a structure of the following for- 

mat: 

struct ufs_args { 

char *fspec; 
}; 

fspec points to the name of the block special file that is to be mounted. This is identical in use and func- 
tion to the first argument for mount(2). 

MOUNT_CDPS Mount a local CD-ROM file system, data points to a structure of the following 

format: 

struct cdfs_args { 

char * fspec; 
}; 

fspec points to the name of the block special file that is to be mounted. 

NETWORKING FEATURES 

NFS 

An additional value for the type argument is supported. 

MOUNT_NFS Mount an NFS file system, data points to a structure of the following format: 

ttinclude <nfs/nfs.h> 
ttinclude <netinet/in.h> 
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struct nfs_args { 



struct 


sockaddr in 


*addr; 


f handle 


>_t 


*fh; 


int 


flags; 




int 


wsize; 




int 


rsize; 




int 


t imeo ; 




int 


retrans; 




char 


♦hostname; 




int 


acregmin; 




int 


acregmax; 




int 


acdirmin; 




4 _ J_ 
J.11L. 


acdiriuax; 





}; 
Elements in the structure as as follows: 

addr Points to a local socket address structure (see inet(7)), which is used by the system to 

communicate with the remote file server. 

f h Points to a structure containing a file handle, an abstract data type that is used by 

the remote file server when serving an NFS request. 

f lags Bit map that sets options and indicates which of the following fields contain valid 

information. The following values of the bits are defined in <nf s /nf s . h>: 

NPSMNT_SOPT Specify whether the mount is a soft mount or a hard 

mount. If set, the mount is soft and will cause requests to 
be retried retrans number of times. Otherwise, the 
mount is hard and requests will be tried forever. 

NFSMNT_WSIZE Set the write size. 

NF SMNT_R SIZE Set the read size . 

NFSMNT_TIMEO Set the initial timeout value. 

NFSMNT_RETRANS Set the number of request retries. 

NFSMNT_HOSTNAME 

Set a hostname. 

Set the option to have interruptible I/O to the mounted file 
system. 

Set the option to deny access to local devices via NFS device 
files. By default, access to local devices via NFS device files 
is allowed. 



NPSMNT INT 



NPSMNT NODEVS 



NFSMNT_IGNORE Mark the file system type as ignore in /etc/mnttab. 

NFSMNT_NOAC Turn off attribute caching. By default NFS caches attri- 

butes of files and directories to speed up operations on NFS 
files by not always getting the attributes from the server. 
Names are also cached to speed up path name lookup. 
However it does allow modifications to files on the server to 
not be immediately detectable on the clients. Setting 
NFSMNT_NOAC turns off attribute caching and name 
lookup caching. NFS caches attributes for a length of time 
proportional to how much time has elapsed since the last 
modification. The time length is subject to acregmin, 
acregmax, acdirmin, and acdirmax described below. 

NFSMNT_NOCTO Cached attributes are flushed when a NFS file is opened 
unless this option is specified. This option is useful where 
it is known that the files will not be changing as is the case 
for a CD-ROM drive. 
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NPSMNT_ACREGMIN 

Use the acregmin value. See acregmin below. 

NPSMNT_ACDIRMIN 

Use the acdirmin value. See acdirmin below. 

NFSMNT_ACREGMAX 

Use the ac re gmax value. See acregmax below. 

NFSMNT_ACDIRMAX 

Use the acdirmax value. See acdirmax below. 

wsize 

Can be used to advise the system about the maximum number of data bytes to use for a single outgo- 
ing protocol (such as UDP) message. This value must be greater than 0. Default wsize is 8192. 

rsize 

Can be used to advise the system about the maximum number of data bytes to use for a single incom- 
ing protocol (such as UDP) message. This value must be greater than 0. Default rsize is 8192. 

timeo 

Can be used to advise the system on the time to wait between NFS request retries. This is in units of 
0.1 seconds. This value must be greater than 0. Default t imeo is 7. 

retrans 

Can be used to advise the system about the number of times the system will resend a request. This 
value must be or greater. Default retrans is 4. 

hostname 

A name for the file server that can be used when any messages are given concerning the server. The 
string can be of length from to 32 characters. 

acregmin 

can be used to advise the system the minimum number of seconds to cache attributes for a non- 
directory file. If this number is less than 0, it means to use the system denned maximum of 3600 
seconds. The number specified can not be 0. If the number is greater than 3600, 3600 will be used. 
Default acregmin is 3. is ignored if NPSMNT_NOAC is specified. 

acdirmin 

can be used to advise the system the minimum number of seconds to cache attributes for a directory. 
If this number is less than 0, it means to use the system defined maximum of 3600 seconds. The 
number specified can not be 0. If the number is greater than 3600, 3600 will be used. Default 
acdirmin is 30. acdirmin is ignored if NFSMNT_NOAC is specified. 

acregmax 

can be used to advise the system the maximum number of seconds to cache attributes for a non- 
directory file. If this number is less than 0, it means to use the system defined maximum of 36000 
seconds. The number specified cannot be 0. If the number is greater than 36 000, 36 000 is used. m 

Default acregmax is 60. acregmax is ignored if NFSMNT_NOAC is specified. I 

acdirmax can be used to advise the system the maximum number of seconds to cache attributes for a 
directory. If this number is less than 0, it means to use the system defined maximum of 36 000 seconds. 
The number specified cannot be 0. If the number is greater than 36 000, 36 000 will be used. Default 
acdirmax is 6 0. acdirmax is ignored if NPSMNT_NOAC is specified. 

RETURN VALUE 

Upon successful completion, vf smount ( ) returns a value of 0. Otherwise, no file system is mounted, a 
value of -1 is returned, and errno is set to indicate the error. 

ERRORS 

vf smount ( ) fails when one of the following occurs: 

[EBUSY] dir is not a directory, or another process currently holds a reference to it. 

[EBUSY] No space remains in the mount table. 

[EBUSY] The super block for the file system had a bad magic number or an out-of-range block size. 
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[EBUSY] Not enough memory was available to read the cylinder group information for the file sys- 

tem. 

[EFAULT] data or dir points outside the allocated address space of the process. 

[EINVAL] dir is a context-dependent file (see cdf(4). 

[EIO] An I/O error occurred while readin CT from or writing to the file system. 

[EIO] An attempt was made to mount a physically write protected or magnetic tape file system as 

read-write. 

[ELOOP] Too many symbolic links were encountered while translating the path name of file system 

referred to by data or dir. 

[ENAMETOOLONG] 

The path name of the file system referred to by data or dir is longer than PATH_MAX 
bytes, or the length of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

[ENOENT] The file system referred to by data or dir does not exist. 

[ENOENT] The file system referred to by data does not exist. 

[ENOTBLK] The file system referred to by data is not a block device. This message can occur only dur- 
ing a local mount. 

[ENOTDIR] A component of the path prefix in dir is not a directory. 

[ENOTDIR] A component of the path prefix of the file system referred to by data or dir is not a direc- 

tory. 

[ENXIO] The major device number of the file system referred to by data is out of range (indicating 

that no device driver exists for the associated hardware). 

[EOPNOTSUPP] vf smount ( ) of a remote device was attempted. 

[EPERM] The caller does not have appropriate privileges. 

DEPENDENCIES 

NFS: vf smount ( ) fails when one of the following occurs, and returns the error indicated: 

[EFAULT] A pointer in the data structure points outside the process's allocated address space. 

[EINVAL] A value in a field of data is out of proper range. 

[EREMOTE] An attempt was made to remotely mount a file system that was already mounted from 
another remote node. 

Seegetfh(2), inet(7\ and mountd(TM) for more information. 

HP Clustered Environment: 

vf smount ( ) of a local CDFS file system (MOUNT_CDPS) is not supported from a cluster client. 
Such a call returns an EINVAL error. 

WARNINGS 

Use of mountOM) is preferred over vf smount ( ) because mountOM) supports all mounting options that 
are available from vf smount ( ) directly, plus mount (1M) also maintains the /etc/mnttab file which 
lists what file systems are mounted. 

In the HP Clustered environment, the spec and dir arguments should always be fully expanded pathnames. 

AUTHOR 

vf smount ( ) was developed by HP and Sun Microsystems, Inc. 

SEE ALSO 

mount(2), umount(2), mount(lM). 
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NAME 

wait, waitpid, wait3 - wait for child or traced process to stop or terminate 

SYNOPSIS 

#include <sys/wait.h> 

pid_t wait (int *stat_loc); 

pid_t waitpid(pid_t pid, int *stat_loc, int options); 

pid_t wait3(int *stat_loc, int options, int *reserved) ; 

DESCRIPTION 

wait () suspends the calling process until one of the immediate children terminates or until a process 
being traced stops because that traced process has hit a break point. A process being traced can be either a 
child or a process attached by the ptrace() request PT_ATTACH (see ptrace (2)). The wait ( ) system 
call returns prematurely if a signal is received. If a child or traced process stops or terminates prior to the 
call on wait, return is immediate. 

If statjoc is not a null pointer, status information is stored in the location pointed to by statjoc. The 
status can be used to differentiate between stopped and terminated processes. If the process terminates, 
the status identifies the cause of termination and passes useful information to the calling process. This is 
accomplished using the following macros denned in <sys/wait .h>, with the status value stored at 
*stat_loc as an argument: 

WIFEXITED (stat_val) If the process terminated because of an exit ( ) or _exit ( ) system 
call, this macro evaluates to a non-zero value. 

WEXITSTATUS (statjual ) 

If the value of WIFEXITED (statjual ) is non-zero, this macro evaluates to 
the low-order 8 bits of the argument that the process passed to exit ( ) or 
_exit ( ) (see exit(2)). 

WIPSIGNALED (statjual ) 

If the process terminated due to the default action of a signal (see sig- 
nal(5)), this macro evaluates to a non-zero value. 

WTERMSIG (statjual ) If the value of WIFS I GNALED (statjual ) is non-zero, this macro evaluates 
to the number of the signal that caused the termination. 

WCOREDUMP {statjual ) If the value of WIFSIGNALED (statjual ) is non-zero, this macro evaluates 
to a non-zero value if a "core image" was produced (see signal(5)). 

WIFSTOPPED {statjual ) If the process is stopped, this macro evaluates to a non-zero value. 

WSTOPSIG (statjual ) If the value of WIFSTOPPED (statjual ) is non-zero, this macro evaluates 
to the number of the signal that caused the process to stop. 

As a single special case, the value stored in *statJoc is zero if and only if status is being returned from a 
terminated process that called exit ( ) or _exit ( ) with a value of zero. 

If the information stored at the location pointed to by statjoc was stored there by a call to one of the m 

wait ( ) functions, exactly one of the macros WIFEXITED ( *stat_loc ) , WIFSIGNALED ( *stat_loc ) , or I 

WIFSTOPPED ( * statjoc ) evaluates to a non-zero value. — 

The waitpid ( ) function behaves identically to wait ( ) if pid has a value of -1 and options has a 
value of zero. Otherwise its behavior is modified by the values of the pid and options arguments. 

The pid argument specifies the set of processes for which status is requested, waitpid returns only the 
status of a child process from this set. 

• If pid is equal to -1, status is requested for any child process or attached process. In this 
respect, waitpid ( ) is then equivalent to wait ( ) . 

• If pid is greater than zero, it specifies the process ID of a single child or attached process for 
which status is requested. 

• If pid is equal to zero, status is requested for any child or attached process whose process group 
ID is equal to that of the calling process. 
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• lipid is less than - 1 , status is requested for any child or attached process whose process group 
ID is equal to the absolute value of pid. 

The options argument is constructed from the bit-wise inclusive OR of zero or more of the following flags: 

WNOHANG If this flag is set, wait pid ( ) or wait 3 ( ) is prevented from suspending the cal- 

ling process. A value of zero is returned indicating that no child or traced processes 
have stopped or died. 

WUNTRACED If and only if this flag is set, waitpid() or wait3 () returns information on 
child or attached processes that are stopped but not traced (with ptrace(2)) because 
they received a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal, and whose 
status has not yet been reported. Regardless of this flag, status is returned for 
child or attached processes that have terminated or are stopped and traced and 
whose status has not yet been reported. 

Calling wait3 ( ) is equivalent to calling waitpid() with the value of pid equal to zero. The third 
parameter to wait 3 ( ) is currently unused and must always be a null pointer. 

If a parent process terminates without waiting for its child processes to terminate, the parent process ID 
of each child process is set to 1. This means the initialization process inherits the child processes. 

Notes 

Earlier HP-UX versions documented the bit encodings of the status returned by wait ( ) rather than the 
macros WIPEXITED, WEXITSTATUS, WIPSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, and 
WSTOPSIG. Applications using those bit encodings will continue to work correctly. However, new applica- 
tions should use the macros for maximum portability. 

In earlier HP-UX versions, the macros WIFSTOPPED, WIFSIGNALED, and WIFEXITED have the same 
definitions as the correspondingly named macros in the BSD 4.3 and earlier systems. Existing applications 
that depend on these definitions will continue to work correctly. However, if the application is recompiled, 
the feature test macro _BSD must be turned on for the compilation so that the old definitions of these mac- 
ros are obtained. New definitions of these macros are in effect by default. The only difference between the 
old and new definitions is the type of the argument. Type union wait is used in the BSD definitions 
while type int is used in the default definitions. 

ERRORS 

wait ( ) fails if one or more of the following is true: 

[ECHILD] The calling process to wait ( ) or wait3() has no existing child or traced 

processes, or the calling process to waitpid ( ) has no existing unwaited-for child or 
traced processes that match the pid argument. 

[ECHILD] For waitpid ( ) , the process or process group specified by pid does not exist or is not 

a child of the calling process. 

[EFAULT] stat_loc points to an illegal address. The reliable detection of this error is implemen- 

tation dependent. 

[EINVAL] The options argument to waitpid () or wait3() is invalid. 

[EINVAL] wait 3 ( ) was passed a non-null pointer value for its third argument. 

[EINTR] The function was interrupted by a signal. The value of the location pointed to by 

stat_loc is undefined. 

RETURN VALUE 

If wait ( ) returns due to the receipt of a signal, a value of -1 is returned to the calling process and 
errno is set to EINTR. If wait ( ) returns due to a stopped or terminated child or traced process, the pro- 
cess ID of that process is returned to the calling process. If waitpidQ or wait3() is called, the WNOHANG 
option is used, and there are no stopped or terminated child or traced processes (as specified hy pid in the 
case of waitpidQ), a value of zero is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 



WARNINGS 

The behavior of wait ( ) , waitpid ( ) , and 
SIG_IGN. See WARNINGS section of signal(5). 



wait3() is affected by setting the SIGCLD signal to 
Signal handlers that cause system calls to be restarted can 
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affect the EINTR condition described above (see sigaction(2), sigvector(2), and bsdproc(2)). 

AUTHOR 

wait ( ) , waitpid ( ) , and wait3 ( ) were developed by HP, AT&T, and the University of California, 
Berkeley. 

SEE ALSO 

Exit conditions ($?) in sh(l), exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5). 

STANDARDS CONFORMANCE 

wait () : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l 

waitpid ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

write, writev - write on a file 

SYNOPSIS 

#include <unistd.h> 

ssize_t write(int fildes, const void *buf, slze_t nbyte) ; 
ffinclude <sys/uio.h> 

ssize_t writev ( 

lnt fildes, 

const struct iovec *iov, 

size_t iovcnt 
) ; 

DESCRIPTION 

write ( ) attempts to write nbyte bytes from the buffer pointed to by bufio the file associated with the file 
descriptor fildes. writev ( ) performs the same action, but gathers the output data from the iovlen 
buffers specified by the elements of the iovec array: iov[0], iov[l], ..., lov[iovcnt-l]. 

The iovec structure for writev () is defined as follows: 

struct iovec { 

c addr _t i o v_ba s e ; 

int iov_len; 

}; 

Each iovec entry specifies the base address and length of an area in memory from which data should be 
copied. The iovec array can be at most MAXIOVlong. 

On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by 
the file offset. Upon return from write ( ) , the file offset is incremented by the number of bytes actually 
written. 

On devices incapable of seeking, writing always takes place starting at the device's current position. The 
value of a file offset associated with such a device is undefined. 

If the 0_APPEND file status flag is set, the file offset is set to the end of the file prior to each write. 

For ordinary files, if the 0_SYNC flag of the file status flags is set, the write does not return until both the 
file data and the file status are physically updated. For block special files, if 0_SYNC is set, the write does 
not return until the data is physically updated. How the data reaches the physical media is 
implementation- and hardware-dependent. 

If the number of bytes requested by write ( ) exceeds the allotted capacity (see ulimit(2)) or the physical 
end of a medium, only the allotted number of bytes are actually written. For example, suppose there is 
space for 20 bytes more in a file before reaching a limit. A write of 512 bytes returns 20. The next write of 
a non-zero number of bytes fails (except as noted below). 

A write to an ordinary file is prevented if enforcement-mode file and record locking is set, and another pro- 
cess owns a lock on the segment of the file being written: 

If 0_NDELAYor 0_NONBLOCK is set, the write returns -1 and sets errno to EAGAIN. 

If 0_NDELAY and 0_NONBLOCK are clear, the write does not complete until the blocking record 
lock is removed. 

If the file being written is a pipe (or FIFO), the system-dependent maximum number of bytes that it can 
store is given by PIPSIZ (defined in <sys/inode . h>). The minimum value of PIPSIZ on any HP-UX 
system is 8192. When writing a pipe, the following conditions apply: 

If the 0_NDELAYor 0_NONBLOCK file status flag is set: 

If nbyte is less than or equal to PIPSIZ and sufficient room exists in the pipe or FIFO, the 
write ( ) succeeds and returns the number of bytes written; 

If nbyte is less than or equal to PIPSIZ but insufficient room exists in the pipe or FIFO, the 
write ( ) returns having written nothing. If 0_NONBLOCK is set, -1 is returned and errno 
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is set to EAGAIN. If 0_NDELAY is set, is returned. 

If nbyte is greater than PIPSIZ and the pipe or FIFO is full, the write returns having written 
nothing. If 0_NONBLOCK is set, -1 is returned and errno is set to EAGAIN. If 0_NDELAY is 
set, is returned. 

If nbyte is greater than PIPSIZ, and some room exists in the pipe or FIFO, as much data as fits 
in the pipe or FIFO is written, and write ( ) returns the number of bytes actually written, an 
amount less than the number of bytes requested. 

If the 0_NDELAYand 0_NONBLOCK file status flags are clear: 

The write ( ) always executes correctly (blocking as necessary), and returns the number of 
bytes written. 

If write ( ) is interrupted by a signal after it successfully writes some data, it returns the number of 
bytes written before the interrupt occurred. If write ( ) is interrupted before any bytes are written, 
write () returns -1 and sets errno to EINTR. 

write ( ) clears the SUID, SGID, and sticky bits on all non-directory type files if the write is performed by 
any user other than the owner or a user who has appropriate privileges. For directories, write ( ) does 
not clear the SUID, SGID, and sticky bits. 

RETURN VALUE 

Upon successful completion, the number of bytes actually written is returned. Otherwise, -1 is returned 
and errno is set to indicate the error. 

ERRORS 

write ( ) fails and the file offset remains unchanged if any of the following conditions is true: 

[EBADF] fildes is not a valid file descriptor open for writing. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for reading by any process. 

[EINTR] A signal was caught before any data was transferred (see sigvector(2). 

[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and 
fcntl(2)). 

[EDQUOT] User's disk quota block limit has been reached for this file system. 

[EAGAIN] Enforcement-mode file and record locking was set, 0_NDELAY was set, and there 

was a blocking record lock. 

[ENOLCK] The system record lock table is full, preventing the write from sleeping until the 

blocking record lock is removed. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring or blocking the SIGTTOU 
signal, and the process group of the process is orphaned. 

[EIO] An I/O error occurred while writing to the device corresponding to fildes . 

[ENOSPC] Not enough space on the file system. 

In addition, writev ( ) might return one of the following errors: 

[EFAULT] iov_base or iov points outside of the allocated address space. The reliable 

detection of this error is implementation dependent. 

[EINVAL] iovcnt is less than or equal to 0, or greater than MAXIOV. 

[EINVAL] One of the iov_len values in the iov array was negative. 

[EINVAL] The sum of iov_len values in the iov array overflowed a 32-bit integer. 

write ( ) or writev ( ) fails, the file offset is updated to reflect the amount of data transferred, and 
errno is set accordingly if one of the following conditions is true: 

[EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the 

maximum file size. See ulimit(2). 
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[EFAULT] buf points outside the process's allocated address space. The reliable detection of 

this error is implementation dependent. 

EXAMPLES 

Assuming a process opened a file for writing, the following call to write(2) attempts to write mybufsize bytes 
to the file from the buffer to which mybuf points. 

#includ© <string*h> 

int mybufsize, nbytes, fildes; 

char *mybuf = "aeiou and sometimes y"; 

mybufsize = strlen (mybuf); 

nbytes = write (fildes, mybuf, mybufsize); 

WARNINGS 

Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can 
affect the behavior described on this page. 

Character special devices, and raw disks in particular, apply constraints on how write ( ) can be used. 
See specific Section (7) manual entries for details on particular devices. 

AUTHOR 

write ( ) was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO 

creat(2), dup(2), lockf(2), lseek(2), open(2), pipe(2), ulimit(2), ustat(2). 

STANDARDS CONFORMANCE 

write ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

intro - introduction to subroutines and libraries 

SYNOPSIS 

ttinclude <stdio.h> 

ttinclude <math.h> 

DESCRIPTION 

This section describes functions found in various libraries, other than those functions that directly invoke 
HP-UX system primitives, which are described in Section (2) of this volume. Certain major collections are 
identified by a letter after the section identifier (3): 

(3C) These functions, together with the Operating System Calls and those marked (3S), consti- 

tute the Standard C Library which is automatically loaded by the C compiler, cc(l). The 
link editor ld(X) searches this library if the -lc option is specified. Declarations for some 
of these functions can be obtained from #include files indicated in the appropriate 
entries. 

(3G) These functions constitute the graphics library, and are documented in separate manuals. 

(31) These functions constitute the instrument support (Device I/O) library. 

(3M) These functions constitute the Math Libraries, 1 ibm . a and libM . a. All of the functions 

are in both libraries except for matherr (see matherr(3M) for more details). The HP-UX 
operating system provides two different libraries due to to conflicts between Issue 2 of the 
SVID specification and the ANSI C standard. If behavior conforming to SVTD Issue 2 is 
desired, libm.a should be used. If behavior conforming to the ANSI C standard is 
desired, libM.a should be used. The libm. a library is automatically linked as needed 
by the Fortran compiler (see /77(1)). Neither is automatically loaded by the C compiler 
(see cc(l)); however, the link editor searches this library if the -lm (for libm.a) or -1M 
(for libM.a) option is specified. Declarations for these functions are available in the 
header file <math.h>. Several generally useful mathematical constants are also defined 
there (see math(5)). 

(3N) These functions are applicable to the Internet network, and are part of the standard C 

library, libc.a. 

(3S) These functions constitute the "standard I/O package" (see stdio(3S)). These functions are 

in the library libc, already mentioned. Declarations for these functions can be obtained 
from the #include file <stdio . h>. 

(3X) Various specialized libraries. The files in which these libraries are found are specified in 

the appropriate entries. 

Definitions 

The word character is used to refer to a bit representation that fits in a byte and represents a single 
graphic character or control function. The null character is a character with value 0, represented in the C 
language as \0. A character array is a sequence of characters. A null-terminated character array is 
a sequence of characters, the last of which is the null character. A string is a designation for a null- 
terminated character array. The null string is a character array containing only the null character. A 
null pointer is the value that is obtained by casting into a pointer. The C language guarantees that two 
null pointers always compare equal, and a null pointer always compares unequal to a pointer to any object 
or function. Consquently, many functions that return pointers return a null pointer to indicate an error. 
The macro NULL expands to a null pointer constant and is defined in <stddef .h> and certain other 
headers. 

Many groups of Fortran intrinsic functions have generic function names that do not require explicit or 
implicit type declaration. The type of the function is determined by the type of its argument or arguments. 
For example, the generic function max returns an integer value if given integer arguments (maxO), a real 
value if given real arguments (amaxl), or a double-precision value if given double-precision arguments 
(dmaxl). 

DIAGNOSTICS 

Functions in the C and Math Libraries, (3C) and (3M), may return the conventional values or 
±HUGE_VAL (the largest-magnitude double-precision floating-point numbers; HUGE_VAL is defined in the 

HP-UX Release 9.0: August 1992 - 1 - 273 



intro(3) intro(3) 



<math.h> header file) when the function is undefined for the given arguments or when the value is not 
representable. Functions in the Math Libraries may also return +INPINITY or NaN. In these cases, the 
external variable errno (see errno(2)) is set to the value EDOM or ERANGE. As many of the Fortran 
intrinsic functions use the routines found in the Math Library, the same conventions apply. 

WARNINGS 

Library routines in libc.a and libm.a often call other routines in these libraries. Prior to HP-UX 
release 7.0, a user could define a function having the same name as one of these library routines, and this 
function would be linked in instead of the library version. In this way, a user could effectively replace a 
library routine with his own (see matfierr(3M) for a supported example of this). More often, this type of 
linkage would occur unintentionally, causing unexpected behavior which was difficult to debug. 

Starting at Release 7.0, object names in libraries have been modified such that they are much less likely to 
collide with user names. Therefore, calls to library routines from within other library routines are much 
more likely to call the actual library routine. (matherr(3M) is the only exception to this.) 

In spite of these changes, it is still remotely possible for name conflicts to occur. The lint(l) program 
checker reports name conflicts of this kind as "multiple declarations" of the names in question. Definitions 
for Sections (2), (3C), and (3S) are checked automatically. Other definitions can be included by using the 
-1 option (for example, -lm includes definitions for the Math Library, libm.a . Use of lintiX) is highly 
recommended. 

FILES 

/lib/hbc.a Standard I/O, operating system calls, and general purpose routines archive library. 

/lib/libc.sl Standard I/O, operating system calls, and general purpose routines shared library. 

/lib/hbcurses.sl CRT screen handling shared library. 

/lib/libm.a SVID2 compliant math archive library. 

/lib/libm.sl SVID2 compliant math shared library. 

/lib/hbM.a XPG3, POSEX.1, ANSI-C compliant math archive library. 

/lib/libM.sl XPG3, POSDC.1, ANSI-C compliant math shared library. 

/usr/hb/libF77.a General Fortran 77 routines archive library. 

/usr/hb/hbF77.sl General Fortran 77 routines shared library. 

SEE ALSO 

intro(2), stdio(3S), math(5), hier(5), ar(l), cc(l), f77(l), ld(l), lint(l), nm(l). 

The introduction to this manual. 

Device HO Library, tutorial in Device I/O Users Guide . 
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NAME 

a64l( ), 164a( ) - convert between long integer and base-64 ASCII string 

SYNOPSIS 

ttinclude <stdlib.h> 

long int a641(const char *s); 
char *164a(long int 1); 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII characters. This is a notation by 
which long integers can be represented by up to six characters; each character represents a "digit" in a 
radix-64 notation. 

The characters used to represent "digits" are . for 0, / for 1, through 9 for 2-11, A through Z for 
12-37, and a through z for 38-63. 

The leftmost character is the least significant digit. For example, 
aO = (38 x 64°) + (2 x 64 *) = 166 

a641 ( ) takes a pointer to a null-terminated base-64 representation and returns a corresponding long 
value. If the string pointed to by s contains more than six characters, a641 ( ) uses the first six. 

164a () takes a long argument and returns a pointer to the corresponding base-64 representation. If 
the argument is 0, 1 64 a ( ) returns a pointer to a null string. 

WARNINGS 

The value returned by 164a ( ) is a pointer into a static buffer, the contents of which are overwritten by 
each call. 

STANDARDS CONFORMANCE 

a641():SVID2 

164a():SVID2 



I 
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NAME 

AAudioString - get name of audio controller (string) passed to AOpenAudio() 

SYNOPSIS 

#include <audio/Alib.h> 

char *AAudioString (Audio *audio); 

DESCRIPTION 

AAudioString () returns the audio jiame (string) that was passed to AOpenAudio() . If audio jiame 
was NULL, the value of the AUDIO variable was used, and that is the value returned. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AAudioString ( ) returns the audio jiame (string) that was passed to 
AOpenAudio ( ) . If audio jiame is NULL, the value of the AUDIO variable is used, and that is the value 
returned. 

ERRORS 

AAudioString ( ) does not return an error status. 

EXAMPLES 

The following call to AAudioString gets the name of the audio controller (string) that was passed to 
AOpenAudio ( ) . 

char *ac_name; /* name of audio 
Audio *audio; /* audio connection */" 



/* get audio controller name */ 
ac_name = AAudioString (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AAudioString ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME ■ 

ABestAudioAttributes - get best audio attribute setting for specified controller I 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AudioAttributes *ABestAudioAttributes (Audio *audio) ; 

DESCRIPTION 

ABestAudioAttributes ( ) returns a pointer to an AudioAttributes structure containing the 
optimal attributes for the audio controller associated with the audio connection. The application can use 
the returned attributes pointer directly in subsequent audio operation calls. 

Changes should not be made to the AudioAttributesstructure; rather, the application should copy the 
structure and make changes in the copy, as shown in the example below. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, ABestAudioAttributes ( ) returns a pointer to an AudioAttri- 
butes structure. 

ERRORS 

ABestAudioAttributes ( ) does not return an error status. 

EXAMPLES 

The following example shows a call to ABestAudioAttributes ( ) to get the pointer to the best audio 
attributes. 

Audio *audio; /* audio connection */" 
AudioAttributes *bestAttr; /* best attributes */" 



/* get best audio attributes */ 
bestAttr = ABestAudioAttributes (audio); 

This example shows how to get a copy of the best attributes and make a change to a field in the copy. The 
program assigns the contents at the returned pointer (the audio attributes) to myAttr and then sets the 
value of the sampledjxttr field in myAttr to ASAFBitPerSample. 

Audio *audio; •/* audio connection */ 

AudioAttributes myAttr; /* my copy of best attributes */ 



/* get copy of audio attributes; change the copy */ 
myAttr = *ABestAudioAttributes (audio) ; 
myAttr . att r . sampled_attr . data_f ormat = ADPALaw 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ABestAudioAttributes ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

abort( ) - generate a software abort fault 

SYNOPSIS 

ttinclude <stdlib.h> 

void abort (void) ; 

DESCRIPTION 

abort ( ) first closes all open files, streams, directory streams, and message catalogue descriptors, if possi- 
ble, then causes the signal SIGABRT to be sent to the calling process. This may cause a core dump to be 
generated (see signal{2)). 

If the signal SIGABRT is caught, the handling function is executed. If the handling function returns, the 
action for SIGABRT is then reset to IG_DFL, and the signal SIGABRT is sent again to the process to 
ensure that it terminates. 

RETURN VALUE 

abort ( ) does not return. 

ERRORS 

No errors are defined. 

APPLICATION USAGE 

SIGABRT is not intended to be caught. 

DIAGNOSTICS 

If SIGABRT is neither caught nor ignored, and the current directory is writable, a core dump is produced 
and the message abort - core dumped is written by the shell. 

SEE ALSO 

adb(l), exit(2), kill(2), signal(2). signal(5). 

STANDARDS CONFORMANCE 

abort ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SIX.1, ANSI C 
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NAME 

abs( ), labs( ) - return integer absolute value 

SYNOPSIS 

#include <stdlib.h> 

int abs (int i) ; 

long int labs (long int i); 

DESCRIPTION 

abs ( ) returns the absolute value of its integer operand. 

labs ( ) is similar to abs ( ) , except that the argument and the returned value each have type long int. 
The largest negative integer returns itself. 

WARNINGS 

In two's-complement representation, the absolute value of the negative integer with largest magnitude is 
undefined. Some implementations trap this error, but others simply ignore it. 

SEE ALSO 

floor(3M). 

STANDARDS CONFORMANCE 

abs ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

labs ( ) : AES, XPG4, ANSI C 
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NAME 

ACalculateLength - return the size in bytes of converted data 

SYNOPSIS 

#include <audio/Alib.h> 

long ACalculateLength ( 

Audio * audio, 

long bufferl_size, 

AudloAttributes *bufferljxttributes, 

AudloAttrlbutes *bujfer2jxttributes, 

long * status jeturn ) ; 

DESCRIPTION 

ACalculateLength ( ) returns the size in bytes of the data in buffer 1 after it is converted to the attri- 
butes oibuffer2jxttributes. 

audio specifies the Audio structure associated with this connection. 

bufferljsize specifies the length in bytes of the data in buffer 1. 

bufferljxttributes specifies the attributes of the data in buffer 1. 

buffer2_attributes specifes the attributes of the data in buffer 2. 

status jeturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ACalculateLength ( ) returns the size in bytes of the data which will be 
produced by converting a source buffer whose size in bytes is specified in bujferl_size and whose attributes 
are specified in bufferljxttributes to the attributes specifed in buffer2_attributes. 

ERRORS 

If status jeturn is not set to NULL, the following is returned in status jreturn: 

AENoError 

EXAMPLE 

For an example, see /usr/audio/examples/splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware installed. To find out whether or not your sys- 
tem has audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ACalculate Length () was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME ■ 

ACheckEvent - get first event found in audio event queue H 

SYNOPSIS 

ttinclude <audio/Alib.h> 

Boolean 

ACheckEvent (Audio *audio, AEvent *event_return, long 

DESCRIPTION 

ACheckEvent ( ) dequeues and returns the first event in the queue and returns TRUE. If the queue is 
empty, the function returns FALSE immediately. This behavior contrasts with APeekEvent ( ) which 
finds but does not dequeue the first event on the queue, and which blocks, if the queue is empty, until an 
event is received. 

audio specifies the Audio structure associated with this connection. 

event_return is the first event found in the queue. 

status_return receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ACheckEvent ( ) returns TRUE or FALSE. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example sets up event to receive event data and status jreturn to receive status data. 

Boolean first_event; /* first event on queue */ 

Audio *audio; /* audio connection */ 

AEvent event_return; /* event_return */ 

long status; /* error status */ 



/* check event queue */ 

first_event = ACheckEvent (audio, & even t_re turn, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ACheckEvent ( ) was developed by HP. 

SEE ALSO 

ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), APeekEvent(3X), 
APutBackEvent(3X), AQLength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface . 
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NAME 

ACheckMaskEvent - get first event in audio event queue that matches mask 

SYNOPSIS 

#include <audio/Alib.h> 

Boolean 
ACheckMaskEvent ( 

Audio *audio, 

AEventMask event_mask, 

AEvent *event_return, 

long *status_return 
); 

DESCRIPTION 

ACheckMaskEvent ( ) dequeues and returns the first event in the queue that matches the mask and 
returns TRUE. If no match is found, the function returns FALSE immediately. Unlike AMaskEvent ( ) , it 
does not block if no match is found. 

audio is the Audio structure associated with this connection. 

eventjnask is the mask specifying what type(s) of event to look for. 

event_return is the first event found in the queue. 

status jreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ACheckMaskEvent ( ) returns TRUE or FALSE. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the event mask to check for errors and transaction started events, and sets up 
event_return to receive event data and status_return to receive status data. 

Boolean f irst_match; /* match found*/ 

Audio *audio; /* audio connection */ 

AEventMask emask; /* event mask */ 

AEvent event_return; /* event return*/ 

long status; /* error status */ 



/* check event queue for mask match */ 

emask = (AErrorMask I ATransStartedMask) ; 

first_match = ACheckEventMask( audio, emask, &event_return, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ACheckMaskEvent ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), APeekEvent(3X), 
APutBackEvent(3X), AQlength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface. 
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NAME 

AChooseAFileAttributes - select attributes to use when creating a new file 

SYNOPSIS 

#include <audio/Alib.h> 

void 
AChooseAFileAttributes ( 

Audio * audio, 

Audi oAt tributes *src_attributes, 

AFileFormat file_format, 

AudioAttrMask user_mask, 

Audi oAt tributes *attributes, 

AByteOrder *byte_order, 

long *status_return 
); 

DESCRIPTION 

AChooseAFileAttributes ( ) selects attributes to use when creating a new file. 

audio specifies the Audio structure associated with this connection. 

src_attributes specifies the audio attributes of the source stream. 

file_format specifes the target file format. 

userjnask specifies which of the audio attributes in the attributes structure have been supplied 

by the user (mask bit set to 1). These attributes are checked for validity, but are not 
changed. 

attributes contains user-supplied attributes (if any) as indicated by userjnask. 

AChooseAFileAttributes ( ) writes appropriate values to those attributes not 
supplied by the user. 

byte_order receives byte ordering for the audio file. 

status_return receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

6 AEBadDataFormat 

7 AEBadFileFormat 
EXAMPLES 

The following example chooses attributes for use when creating a new Sun/NeXT file. 
Audio * audio; /* audio connection */ 

AudioAttributes 

* src_attribs; /* source stream attributes */ 
AFileFormat dest_f ile_format ; /* file format */ 

AudioAttrMask dest_mask; /* attributes set by user */ 
AudioAttributes 

dest_attribs; /* returned attributes */ 
AByteOrder dest_byte_order; /* returned byte order */ 

long status; /* status */ 

dest_f ile_format = AFFSun; 



/* Get the attribute structure for the target file. */ 
/* Specify MuLaw data format and 8k samples/second */ 
dest_att ribs. type = ATSampled; 

dest_attribs.attr.sampled_attr.data_format = ADFMuLaw; 
dest_attribs.attr.sampled_attr .sampling_rate = 8000; 
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dest_mask = ASDataFormatMask I ASSampling Rate Mask; 
AChooseAFileAttributes (audio, src_attribs, dest_f ile_format, 
dest_mask, &dest_attribs, &dest_byte_order, fcstatus) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual shipped with your system. 

AUTHOR 

AChooseAFileAttributes ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface . 
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NAME 

AChoosePlayAttributes - select hardware-supported attributes to use when playing an existing file or a 
stream 

SYNOPSIS 

#include <audio/Alib.h> 



void 

AChoosePlayAttributes 
Audio 

AiluxOntt ITxbuteS 

AudioAttrMask 
AudioAttributes 
AByteOrder 
long 
); 



( 

* audio , 

* srcjxitnbutes , 
userjnask , 

* attributes, 
*byte_order , 
*status return 



DESCRIPTION 

AChoosePlayAttributes ( ) selects hardware-supported attributes to use when playing an existing 
file or a stream. 

audio Specifies the Audio structure associated with this connection. 

srcjxttributes Specifies the audio attributes of the source stream. 

userjnask Specifies which of the audio attributes in the attributes structure have been supplied 

by the user (mask bit set to 1). These attributes are checked for validity, but are not 
changed. 

attributes Contains user-supplied attributes (if any) as indicated by userjnask. 

AChoosePlayAttributes Writes appropriate values to those attributes not sup- 
plied by the user. 

bytejorder Receives the byte ordering for hardware. 

status jeturn Receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, the following is returned in status jeturn: 

AENoError 

EXAMPLE 

For an example, see /usr/audio/examples/splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AChoosePlayAttributes ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 



AChooseSourceAttributes - select attributes to associate with an existing file or a stream 



SYNOPSIS 

#include <audio/Alib.h> 
<stdio.h> 



APilePormat 
AChooseSourceAttributes 



( 



Audio 

char 

FILE 

AFileFcnaat 

AudioAttrMask 

Audi oAt tributes 

long 

long 

AByteOrder 

long 



* audio, 

* pathname, 

* audiofile, 

user_mask, 

* attributes, 

* offset, 

* data_length, 

* bytejorder, 

* status jreturn ) ; 



DESCRIPTION 

AChooseSourceAttributes ( ) selects attributes to associate with an existing file or a stream. 

audio specifies the Audio structure associated with this connection. 

pathname specifies the pathname of the audio file. Ignored if audiofile is NULL. 

audiofile specifies the file pointer if the source is a file. If the source is a stream, such as stdin, 

set audiofile to NULL . 

filejbrmat specifies the format of the file. Maybe AFFUnknown. 

userjnask specifies which of the audio attributes in the attributes structure have been supplied 

by the user (mask bit set to 1). These attributes will be checked for validity, but will 
not be changed. 

attributes contains user-supplied attributes (if any) as indicated by user_mask. 

AChooseSourceAttributes will write appropriate values to those attributes not 
supplied by the user. 

offset receives the location, in bytes, where the audio data begins. 

datajength receives the length, in bytes, of the audio data. 

byte_order receives the byte ordering of the data in the file. 

statusjreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AChooseSourceAttributes ( ) returns the format of the file if the 
source is a file. If the source is a stream or the file format cannot be determined, AFFUnknown is returned. 

ERRORS 

If statusjreturn is not set to NULL, one of the following is returned in status j-eturn: 

AENoError 

2 AEBadAudio 

6 AEBadFileFormat 

7 AEBadDataFormat 
11 AEBadFileHdr 

17 AEOutOfMemory 

EXAMPLE 

For an example, see /usr/audio/examples/splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
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audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AChooseSourceAttributes ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

ACloseAudio - close connection to specified audio server 

SYNOPSIS 

# include <audio/Alib.h> 

void ACloseAudio (Audio *audio, long *status_return) ; 

DESCRIPTION 

ACloseAudio ( ) closes the connection to the server specified by audio and deallocates the Audio struc- 
ture memory. 

ACloseAudio ( ) waits for the audio server to acknowledge that the audio connection is closed before 
returning. After the connection has been closed, it cannot be resumed or used in any other way. 

audio specifies the Audio structure associated with this connection. 

status_return receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jretum. 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example closes the connection to audio and sets up status to receive status data. 

Audio *audio; /* audio connection */ 
long status; /* error status */ 



/* close audio connection */ 
ACloseAudio (audio, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ACloseAudio ( ) was developed by HP. 

SEE ALSO 

AOpenAudio(3X). 

Using the Audio Application Program Interface. 
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NAME 

acltostr() - convert access control list (ACL) structure to string form 

SYNOPSIS 

#include <acllib.h> 

char *acltostr (int nentries, const struct acl_entry *acl, int form); 

Remarks: 

To ensure continued conformance with emerging industry standards, features described in this manual 
entry are likely to change in a future release. 

DESCRIPTION 

acltostr ( ) converts an access control list from structure form to string representation, acltostr ( ) 
takes a pointer to the first element of an array of ACL entries (acl), containing the indicated number (nen- 
tries) of valid entries (zero or more), and the output form desired (FORM_SHORT or FORM_LONG). It 
returns a pointer to a static string (overwritten by the next call), which is a symbolic representation of the 
ACL, ending in a null character. The output forms are described in acl(5). In long form, the string returned 
contains newline characters. 

A user ID of ACL_NSUSER and a group ID of ACL_NSGROUP are both represented by %. As with the Is 
command (see Zs(l)), if an entry contains any other user ID or group ID value not listed in /et c/passwd 
or /etc/group, acltostr ( ) returns a string equivalent of the ID number instead. 

Just as in routines that manage the /etc/passwd file, acltostr ( ) truncates user and group names 
to eight characters. 

Note: acltostr ( ) is complementary in function to strtoacl ( ) . 

RETURN VALUE 

If acltostr ( ) succeeds, it returns a pointer to a null-terminated string. If nentries is zero or less, the 
string is of zero length. If nentries is greater than NACLENTRIES (defined in <sys/acl .h>), or if form 
is an invalid value, the call returns (char *) NULL. 

EXAMPLES 

The following code fragment reads the ACL on file /users /ggd/t est and prints its short-form represen- 
tation. 

#include <stdio.h> 
ttinclude <aclllb.h> 

Int nentries; 

struct acl_entry acl [NACLENTRIES] ; 

If ((nentries = getacl ("/users/ggd/test", NACLENTRIES, acl)) < 0) 
error (...); 

fputs (acltostr (nentries, acl, FORM-SHORT ) , stdout) ; 

AUTHOR 

acltostr ( ) was developed by HP. 

FILES 

/etc/passwd 
/etc /group 

SEE ALSO 

getacl(2), setacl(2), cpacl(3C), chownacl(3C), setaclentry(3C), strtoacl(3C), acl(5). 
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NAME 

AConnectionNuinber - get connection number for specified audio server connection 

SYNOPSIS 

#include <audio/Alib.h> 

long AConnectionNuinber (Audio *audio); 

DESCRIPTION 

AConnect ionNumber ( ) gets the number for the audio server connection specified by audio . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AConnectionNuinber ( ) returns the connection number for the specified 
audio server connection. 

ERRORS 

AConnectionNuinber does not return an error status. 

EXAMPLES 

The following example gets the number for the audio connection specified by audio. 

Audio *audio; /* audio connection */" 
long conn; /* connection number */" 



/* get number of audio connection */ 
conn = AConnectionNuinber (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AConnectionNuinber ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

AConnectRecordSStream - connect socket to TCP socket address; return transaction ID 

SYNOPSIS 

ttinclude < audio/ Alib.h> 

ATransID AConnectRecordSStream ( 

Audio * audio, 

SStream *remote_sstream / 

SSRecordParams *rp, 

long *status_return 
); 

DESCRIPTION 

AConnectRecordSStream ( ) is used by an application that is preparing to send a record sound stream 
to a server on another system. After creating a socket, the application calls AConnec- 
tRecordSStream () to connect it to the other server at the TCP socket address contained in 
remote _str earn, the pointer to which it obtains from the application that controls the other server. The call 
returns a transaction ID for the operation. 

audio specifies the Audio structure associated with this application's connection to its own 

server. 

remote jsstr earn is a structure containing a TCP socket address, audio attributes, and the maximum block 
size, in bytes, of each transfer of audio data over the connection. 

rp is the structure containing the record gain, pause_first toggle, gain matrix, and the mask 

for event notification. 

status_return receives the returned status of the operation unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AConnectRecordSStream ( ) returns a transaction ID. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jretum: 

AENoError 

2 AEBadAudio 

10 AEBadGainMatrix 

21 AEBadSoundStream 

EXAMPLES 

The following example connects a socket to another server's TCP socket address and returns a transaction 
ID for the operation. 

ATransID xid; /* transaction ID */ 

Audio *audio; /* audio connection */ 

SStream *r_sstream; /* remote stream descrip */ 

SSRecordParams *ss_rp; /* sstream record params */ 

long status; /* error status */ 



/* connect to TCP socket addr and get transID */ 

xid = AConnectRecordSStream (audio, r_sstream, ss_rp, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AConnectRecordSStream ( ) was developed by HP. 

SEE ALSO 

APlaySStream(3X),ARecordSStream(3X). 
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Using the Audio Application Program Interface. 
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NAME 

AConvertAFile - convert audio file data format 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AConvertAFile ( 
Audio *audio, 
char *src_pathname, 
APileFormat src_f ile_f ormat, 

Cii&r "Q6Su pciuijIialTLS/ 

AFileFormat dest_file_f ormat, 
AudioAttrMask dest_attr_mask, 
AudioAttributes *dest_attributes, 
long *status_return 
); 

DESCRIPTION 

AConvertAFile ( ) converts the data in src_pathname according to the format specified in 
dest_file_format and the attributes in destjxttributes. The results are written to dest_pathname . 

Arguments 

audio 



I 



src_pathname 
src_file_format 



Audio structure associated with this connection. 

Pathname of the source file. 

File format of the source file. If this parameter is set to AFFUnknovm, the conversion 
utility attempts to determine the file format from the filename extension, if one exists, 
or from the file contents. 

If there is no determinable file format, an error is returned; there is no default. 

Valid file type extensions are: 



• u 


Mulaw 


.al 


Alaw 


.au 


Sun(NeXT) 


.wav 


Riff 


. snd 


NeXT 


.116 


Linear 16 


.18 


Linear8 


.lo8 


Linear80ffset 



dest_pathname 

dest_ftle_format 

destjxttrjnask 

destjxttributes 
status return 



If you have a "Mac" file, try treating it as a raw data file in Linear80ffset with a sam- 
pling rate of 22k or another sampling rate. 

Pathname of the destination file. 

File format of the destination file. 

Audio attributes to be used in destjxttributes. The mask is a bitwise inclusive OR of 
the values defined in AudioAttrMask. If this mask is set to 0, values are used 
from the source file wherever they are appropriate for files of type destJUeJbrmat. 

Attributes that are affected by the mask. If set to NULL, the attribute mask is 
cleared, and values are used from the source file wherever they are appropriate for 
files of type destjilejormat. For attributes to be valid, type must be set, separate 
from the mask. 



Receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

2 AEBadAudio 

6 AEBadFileFormat 
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7 AEBadDataFormat 

8 AEFileNotFound 

11 AEBadFileHdr 

12 AEUnrecognizableFormat 

13 AEBadAttribute 

16 AECantDetermineFormat 

EXAMPLES 

The following example converts the data in /mydir/ audfile.wav to a 30-second Sun (NeXT) format 
"mono" Mulaw file, sampled at 8000 samples per second, and writes the result in /mydir/audf ile .au. 

Audio *audio; /* audio connection */ 

AFileFormat src_fmt; /* source file format */ 

AFileFormat dest_fmt; /* destination file format */ 

AudioAttrMask a_mask; /* audio attributes mask */ 

AudioAttributes dest_attr; /* destination attributes */ 

long status; /* error status */ 



/* convert audio file */ 

static char s_name [ ] = {"/mydir/auf ile.wav"}; 

src_fmt = AFFUnknown; /* let AAPI determine file type */ 

static char d_name [ ] = {"/mydir/auf ile.au"}; 
dest_fmt = AFFSun; /* Sun (NeXT) format */ 

a_mask = ; 

dest_attr.type = ATSampled; /* must set this */ 
dest_attr . attr . sampled_attr . data_f ormat = ADFMulaw; 
a_mask = a_mask | ASDataFormatMask; 
dest_attr.attr.sampled_attr.sampling_rate = 8000; 
a_mask = a_mask I ASSamplingRateMask; 
dest_attr. attr. sampled_attr. channels =1; 
a_mask = a_mask I ASChannelsMask; 

dest_attr. attr. sampled_attr. duration. type = ATTMilliseconds; 
dest_attr. attr. sampled_attr. duration. milliseconds = 30000; 
a_mask = a_mask | ASDurationMask; 

AConvertAFile (audio, s_name, src_fmt, d_name, dest_fmt, 
a_mask, &dest_attr,&status) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AConvertAFile ( ) was developed by HP. 

SEE ALSO 

ALoadAFile(3X), ASaveSBucket(3X). 

Using the Audio Application Program Interface. 
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NAME 

AConvertBuffer - convert a buffer of data 



I 



SYNOPSIS 








# include 


<audio/Alib. 


.h> 


void 








AConvertBuffer 


( 




Audio 






* audio, 


AConverfcParains 


* convert jparam-s, 


char 






* srcjbuffer, 


long 






src_buffer_size, 


char 






* destjbuffer, 


long 






destjbuffer jsize, 


long 






* bytes_read, 


long 






* bytes _written, 


long 






* status jreturn ) ; 



DESCRIPTION 

AConvertBuffer ( ) converts the data in srcjbuffer according to the attributes specified in 
convert jparams and puts the results in destjbuffer. Conversion will stop when either all the data in the 
source buffer has been converted or the destination buffer is full. If the destination buffer fills up before all 
the source data is converted, bytes jread will be less than srcjbuffer _size. If the source buffer empties before 
the destination buffer is full, bytes jvritten will be less than destjbuffer jsize 

audio specifies the Audio structure associated with this connection. 

convert_params Pointer to a structure describing conversion source and destination; returned by 

ASetupConversion . 

srcjbuffer data to be converted. 

srcjbuffer _size size in bytes of the source buffer, srcjbuffer. 

destjbuffer the destination buffer; receives the converted data. 

dest_buffer_size size in bytes of the destination buffer. 

bytesjread receives the number of bytes read. 

bytesjuuritten receives the number of bytes written. 

status jreturn receives the returned status of the operation, unless it is set to NULL. 
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ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

13 AEBadAttribute 

17 AEOutOfMemory 

EXAMPLE 

For an example, see /usr /audio/examples /splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AConvert Buffer ( ) was developed by HP. 

SEE ALSO 

ASetupConversion(3X),AEndConversion(3X) 

Using the Audio Application Program Interface. 
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NAME 

ACreateSBucket - create empty sound bucket and return pointer to it 

SYNOPSIS 

#include <audio/Alib.h> 

SBucket * 

ACreateSBucket ( 

Audio *audio, 

AudioAttrMask attrjmask, 

Audi ©Attributes *audio att ributes,- 

long *status_return 
); 

DESCRIPTION 

ACreateSBucket ( ) creates an empty sound bucket to receive recorded data, associates it with audio 
attributes, and returns the pointer to it. 

audio specifies the Audio structure associated with this connection. 

attrjnask is the mask used to select attributes 

audio jattrib utes 

is the structure containing the audio type and attributes. Audio type must be set. 

status jretum receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ACreateSBucket ( ) returns a pointer to a sound bucket. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

2 AEBadAudio 

7 AEBadDataFormat 

13 AEBadAttribute 

17 AEOutOfMemory 

19 AEBadSamplingRate 

EXAMPLES 

The following example creates sound bucket sb and selects Bit Per Sample and Duration attributes: 

SBucket *sb; /* sound bucket */ 

Audio *audio; /* audio connection */ 

AudioAttrMask amask; /* audio attributes mask */ 

AudioAttributes *attr; /* audio attributes */ 

long status; /* error status */ 



/* create sound bucket */ 

amask = (ASAPBitPerSample I ASAFDuration) ; 

sb = ACreateSBucket (audio, amask, attr, &status) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ACreateSBucket ( ) was developed by HP. 

SEE ALSO 

ADestroySBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), APlaySBucket(3X), APutSBucketData(3X), 
ARecordAData(3X), ASaveSBucket(3X). 
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Using the Audio Application Program Interface. 
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NAME 

ADataFormats - get list of data formats supported by audio controller 

SYNOPSIS 

ttinclude <audio/Alib.h> 

ADataPormat *ADataPormats (Audio *audio) ; 

DESCRIPTION 

ADataFormats ( ) returns a pointer to a list of the data formats that are supported by the audio con- 
troller associated with the audio connection. The length of the list is returned by ANumDataFormat s ( ) . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

On successful completion, ADataFormats ( ) returns a pointer to a list of data formats that are sup- 
ported by the audio controller. 

EXAMPLES 

The following example gets a list of data formats that are supported by the audio controller associated with 
audio. 

ADataFormat *list_fmts; /* list of data formats */ 
Audio *audio; /* audio connection */ 



/* get list of data formats */ 
list_fmts = ADataFormats (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ADataFormats ( ) was developed by HP. 

SEE ALSO 

ANumDataFormats(3X) . 

Using the Audio Application Program Interface. 
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NAME 

addopt() - add argument and data to NetlPC option buffer 

SYNOPSIS 

#lnclude <sys/ns_ipc.h> 

void addopt ( 

short opt [}, 
short argnum, 
short optioncode, 
short datalength, 
short data [ ] , 
short *result); 

DESCRIPTION 

addopt ( ) adds an argument and its associated data to a NetlPC opt buffer. A NetlPC option buffer is a 
data array structured and used by NetlPC . The size of the data array can be determined by calling opt- 
overhead ( ) (see optoverhead (3N)). The buffer must be initialized by calling initopt ( ) (see 
initopt(3N)). 

Parameters 

opt (input parameter) The opt buffer to which you want to add an argument. 

argnum (input parameter) The number of the argument to be added. The first argument is number 

zero. 

optioncode (input parameter) The option code of the argument to be added. These codes are described 

in each NetlPC system call opt parameter description. 

datalength (input parameter) The length in bytes of the data to be included. This information is pro- 
vided in each NetlPC system call opt parameter description. 

data (input parameter) An array containing the data associated with the argument. 

result (output parameter) The result code returned. Refer to "Diagnostics" below for more infor- 

mation. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

[NSR_ADDR_OPT] An unknown or illegal option number was specified. 

[NSR_NO_ERROR] The call was successful. 

[NSR_OPT_DATA_LEN] The length of the opt parameter is less than 0. 

[NSR_OPT_ENTRY_NUM] Option index is less than or greater than the option buffer for which it was ini- 
tialized. If an option buffer is initialized for 3 options, number the options as 0, 
1, and 2. In this example, the number 3 is illegal. 

AUTHOR 

addopt ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), initopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(3N). 
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NAME ■ 

ADestroySBucket - destroy specified sound bucket I 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void ADestroySBucket ( 

Audio * audio, 

SBucket *sb, 

long *status_return 
); 

DESCRIPTION 

ADestroySBucket ( ) destroys the specified sound bucket and frees the space allocated for the sound 
bucket and its audio data. 

audio specifies the Audio structure associated with this connection. 

sb specifies the sound bucket to be destroyed. 

status ^return receives the returned status of the operation, unless it is set to NULL. 

Once it has been destroyed, a sound bucket cannot be used to play or record. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 
2 AEBadAudio 
20 AEBadSoundBucket 

EXAMPLES 

The following example destroys the sound bucket sb and frees its allocated space. 

Audio *audio; /* audio connection */ 

SBucket *sb; /* sound bucket */ 

long status; /* error status */ 



/* destroy sound bucket */ 
ADestroySBucket (audio, sb, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ADestroySBucket ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), APlaySBucket(3X), APutSBucketData(3X), 
ARecordAData(3X), ASaveSBucket(3X). 

Using the Audio Application Program Interface. 
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NAME 

AEndConversion - finish stream data conversion 

SYNOPSIS 

#include <audio/Alib.h> 

void 

/iJuQCIuOuvc j. a j. uu \ 

Audio * audio, 

AConvertParams * convert_params, 

char * destjbuffer, 

long destjbuffer _size, 

long * bytes jvritten, 

long * status jreiurn ) ; 

DESCRIPTION 

AEndConversion ( ) converts any data remaining in the conversion pipeline to the attributes specified 
in convert_params and puts the results in destjbuffer. The amount of data written is returned in 
bytes jvritten . AEndConversion also frees the structure, convert_params . 

audio specifies the Audio structure associated with this connection. 

convert jparams pointer to a structure describing conversion source and destination; returned by 

ASetupConversion . 

destjbuffer the destination buffer; receives the converted data. 

destjbuffer _size size in bytes of the destination buffer. 

bytesjvritten receives the number of bytes written. 

statusjreturn receives the returned status of the operation, unless it is set to NULL. 
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ERRORS ■ 

If status _return is not set to NULL, one of the following is returned in status _return: | 

AENoError 

EXAMPLE 

For an example, see /usr/audio/examples/splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AEndConversion ( ) was developed by HP. 

SEE ALSO 

ASetupConversion(3X),AConvertBuffer(3X), 

Using the Audio Application Program Interface. 
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NAME 

AEventsQueued - get number of events in queue for specified server connection 

SYNOPSIS 

ttinclude <audio/Alib.h> 

long AEventsQueued ( 

Audio *audio, AQueueCheckMode mode, 

long *status_return 
); 

DESCRIPTION 

AEvents Queued ( ) returns the number of events in the queue for the specified audio server, depending 
on mode . 

audio specifies the Audio structure associated with this connection. 

mode is AQueuedAl ready or AQueuedAf terReading. 

If the mode is AQueuedAl ready, the call returns the number of events in the queue 
including zero. If the mode is AQueuedAf terReading and there are no events on the 
queue, the function tries to determine whether the server has more events for this connec- 
tion, and returns the number it finds. If there are none, it returns zero. 

status_return receives the returned status of the operation unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AEventsQueued ( ) returns the number of events in the queue for the 
specified server connection, depending upon the mode. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example gets the number of events on the queue for the audio server connection specified by 
audio and sets up status to receive an error status. The mode is set to AQueuedAl ready so that the call 
will return zero if there are no events in the queue. 

long e_num; /* number of events in q */ 

Audio *audio; /* audio connection */ 

AQueueCheckMode mode; /* check mode */ 

long status; /* error status */" 



/* check event queue */ 

mode = AQueuedAl ready; 

e_num = AEventsQueued (audio, mode, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AEventsQueued() was developed by HP. 

SEE ALSO 

ACheckEvent(3X) ACheckMaskEvent(3X), AMaskEvent(3X), ANextEvent(3X), APeekEvent(3X), 
APutBackEvent(3X), AQLength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface . 
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NAME 

AGetAFileAttributesQ - get file attributes of specified file 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AFileFormat AGetAFileAttributes ( 
Audio *audio, 
char *name / 
long *offset, 
long *data_length, 
AByteOrder *f ile_byte_order, 
AudioAttrMask *mask, 
AudioAttributes *file_attr, 
long *status_return 
); 
DESCRIPTION 

AGetAFileAttributes ( ) returns the file format of the file specified in name, 
audio specifies the Audio structure associated with this connection. 

name the pathname of the audio data file to be queried. 

offset receives the number of bytes into the file where the audio samples begin. 

datajength receives the length (in bytes) of the audio data. 

file_byte_order receives the byte order (relevant only for 116 data). 

mask receives the information indicating which attributes were determined from file header 

or file extension (mask bits set to 1). A mask bit set to indicates that the attribute 
was determined by inference. 
filejxttr attribute structure that receives requested attribute information. 

status jreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AGetAFileAttributes () returns the file type of the file specified in 
name . It also returns the length, the byte order, the attributes, and a mask that indicates how the attri- 
bute values were derived. AFFUnknown is returned if the format type cannot be determined. 
ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 
AENoError 
2 AEBadAudio 
8 AEFileNotFound 
11 AEBadFileHdr 
13 AEBadAttribute 
16 AECantDetermineFormat 

EXAMPLES 

The following example queries the file attributes of the file /myhome/a_dir/a_f ile. 

AFileFormat file_fmt; /* file format */ 

Audio *audio; /* audio connection */ 

long offset; /* offset where data begins */ 

long data_length; /* returned data length */ 

AByteOrder byte_order; /* returned byte order */ 

AudioAttrMask attr_mask; /* attr found in hdr or .ext */ 

AudioAttributes attribs; /* returned attributes */ 

long status; /* status */ 



/* get attributes of /myhome/a_dir/a_f ile */ 

charfname[] = /myhome/a_dir/a_file ; 

file_fmt = AGetAFileAttributes (audio, fname, fcoffset, &data_len, 

&byte_order, &attr_mask, fcattribs, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
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audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetAFileAttributes ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME ■ 

AGetChannelGain - get transaction channel gain ■ 

SYNOPSIS 

# include < audio /Alib.h> 

void AGetChannelGain ( 

Audio *audio, 

ATransID xid, 

AChType channel, 

AGainBB *gain_return, 

long *status_return 
); 

DESCRIPTION 

AGetChannelGain ( ) Returns the transaction gain value. 

audio the Audio structure associated with this connection. 

xid the transaction ID. 

channel the type of channel: ACTMono, ACTLef t, or ACTRight . 

gain_return receives the returned gain value. 

status jreiurn receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn. 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example returns the transaction left channel gain value. 

Audio *audio; /* audio connection */ 

AChType *chtype; /* type of channel */ 

AGainDB chgain_ret; /* transaction gain value*/ 

long status; /* error status */ 



/* get xid left channel gain */ 

chtype = ACTLeft 

AGetChannelGain (audio, xid, chtype, &chgain_ret, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetChannelGain() was developed by HP. 

SEE ALSO 

AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), AInputChannels(3X), 
AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AGetDataFormats - get data formats for a specified file format 

SYNOPSIS 

#include <audio/Alib.h> 

long 
AGetDataFormats ( 

AFileFormat file_formatJ; 

DESCRIPTION 

AGetDataFormats ( ) returns a mask of supported data formats for the file format specified in 
filejbrmat. The returned mask is a long, whose bits correspond to the enum "ADataFormat' denned in 
Alib.h. 



The encoding is: 




/* 


*dataFormatNames [ ] 




Unknown, 
MuLaw, 1 
ALaw, 2 
Linl6, 3 
Lin8, 4 
Lin80ffset, 


*/ 




o 


filejbrmat 


spec 


;ifies the file 



RETURN VALUE 

Upon successful completion, AGetDataFormats ( ) returns a long integer mask of the valid data for- 
mats for the given file format. If the file format itself is invalid, AGetDataFormats returns zero. 
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EXAMPLE 

The following example gets the data formats for a Sun/NeXT file . 

long data_formats_msk; /* supported data formats */ 



/* determine valid data formats for a Sun/NeXT file */ 
data_f ormats_msk = AGetDataFormats (AFPSun) ; 

/* determine if MuLaw is supported */ 

if (data_f ormats_msk & ( 1 << ADFMuLaw ) ) 

/* Mulaw is a supported data type */ 



DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetDataFormats ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

AGetErrorText - copy error description into specified buffer 

SYNOPSIS 

#include <audio/Alib.h> 

void AGetErrorText ( 

Audio * audio., 

AError error, 

char *buf fer_return, 

int buffer_length 
); 

DESCRIPTION 

AGetErrorText ( ) copies the description for the error specified in error to the buffer specified in 
buffer jreturn. The error description is a null-terminated string. 

audio specifies the Audio structure associated with this connection. 

error specifies the type of error. 

buffer jreturn receives the error description. 

buffer Jength specifies the size of buffer jreturn. 

ERRORS 

AGetErrorText ( ) does not return an error status. 

EXAMPLES 

The following example gets the error description for AEBadOf f set and returns it in buffer jreturn: 

#define TEXT_LENGTH 256 

Audio *audio; /* audio connection */ 

AError err; /* type of error */ 

char buffer_retum[TEXT_LENGTH] ; /* buffer for description */ 



/* get error description */ 

err = AEBadOffset 

AGetErrorText (audio, err, &buf fer_return, TEXT_LENGTH) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetErrorText ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

AGetGain - get play volume or record gain of specified transaction 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AGetGain ( 
Audio *audio, 
ATransID xid, 
AGainDB *gain_return 
long *status_return ); 

DESCRIPTION 

AGetGain ( ) returns the play volume or record gain of the transaction specified in xid. 

audio specifies the Audio structure associated with this connection. 

xid specifies the transaction ID. 

gainjreturn receives the returned gain value. 

status_return receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return. 

AENoError 
2 AEBadAudio 
15 AEBadTransactionID 

EXAMPLES 

The following example gets the gain for the xid transaction and sets up status to receive an error status. 

Audio *audio; /* audio connection */ 

TransID xid; /* transaction ID */ 

AGainDB gain_return; /* gain return */ 

long status; /* error status */ 



/* get gain for xid returned by prior call */ 
AGetGain (audio, xid, &gain_return, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetGain ( ) was developed by HP. 

SEE ALSO 

AGMGainRestricte d(3X), AGetSystemMonitorGain(3X), AGetSystemPlayGain(3X), 

AGetSystemRecordGain(3X), AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), 

AMaxOutputGain(3X), AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), 

AOutputDestinations(3X), ASetGain(3X), ASetSystemMonitorGain(3X) ASetSystemPlayGain(3X), 
ASetSystemRecordGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AGetSBucketData - copy audio data in sound bucket to buffer; return number of bytes 

SYNOPSIS 

#include <audio/Alib.h> 

unsigned long AGetSBucketData ( 

Audio *audlo, 

SBucket *sb, 

unsigned long start_of f set, 

char *buffer, 

unsigned long buf_len, 
long *status_return 
); 

DESCRIPTION 

AGetSBucketData ( ) copies the audio data in the specified sound bucket to the specified buffer and 
returns the number of bytes copied. 

audio specifies the Audio structure associated with this connection. 

sb specifies the sound bucket containing the data to be copied. 

start_offset specifies the starting point of the copy, given as the byte offset from the beginning of the 
data. 

buffer specifies the buffer to receive the copied data. 

bufjen specifies the maximum length of the buffer, in bytes . 

status_return receives the returned status of the operation, unless it is set to NULL. 

This call is used only when the application needs to manipulate the sound bucket data directly. 

RETURN VALUE 

Upon successful completion, AGetSBucket ( ) returns the byte count of the copied data. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return: 

AENoError 
2 AEBadAudio 
20 AEBadSoundBucket 

EXAMPLES 

The following example copies the audio data contained in sb to the buffer at bufp and returns the number of 
bytes that were copied. In this example, we allocate 80 000 bytes for the buffer, and pass this size value in 
buflen. 

unsigned long datalen_g; /* copied get_data 
Audio *audio; /* audio connection */ 
SBucket *sb; /* sound bucket*/ 
unsigned long startoff; /* start offset 
char *bufp; /* ptr to buffer 
unsigned long buflen; /* length of 
long status; /* error status */ 



/* copy sound bucket data to buffer */ 

startoff =0; 

bufp = malloc (80000) ; 

buflen = 80000; 

datalen_g = AGetSBucket Data (audio, sb, startoff, bufp, buflen, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
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audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetSBucketData ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), ALoadAFile(3X), APlaySBucket(3X), APutSBucketData(3X), 
ARecordAData(3X), ASaveSBucket(3X). 

Using the Audio Application Program Interface. 



I 



HP-UX Release 9.0: August 1992 - 2 - 313 



AGetSilenceValue ( 3X) AGetSilenceValue ( 3X) 



NAME 

AGetSilenceValue - get a silence value 

SYNOPSIS 

ttinclude <audio/Alib.h> 

long 

AGetSilenceValue ( 

Audio * audio, 

ADataPormat datajormat, 

long * significant_bytes_return, 

long * status jreturn ) ; 

DESCRIPTION 

AGetSilenceValue ( ) returns the appropriate "silence" value for the given data format. (Some data 
formats do not use zero to correspond to silence.) The silence value can be used for clearing or padding an 
audio file or buffer. 

audio specifies the Audio structure associated with this connection. 

datajormat the data format for which a silence value will be returned. 

significant Jbytes_retum 

indicates the number of bytes of the returned long that constitute the actual silence 
value. Currently, all silence values are one byte in length. The application will thus 
need to cast the silence value to an unsigned char before using it. 

statusjreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AGetSilenceValue ( ) returns a long integer containing the silence value 
in the least significant bytes. 
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ERRORS 

If status _return is not set to NULL, the following is returned in status jreturn: 

AENoError 

EXAMPLE 

The following example gets the silence value for MuLaw data. 

Audio * audio; /* audio connection */ 

ADataPormat data_f ormat; /* data format of interest */ 

long signif icant_bytes; /* number valid bytes in returned 

long */ 
unsigned char silence_value; /* pads audio file or buffer with 

silence */ 
long status; /* status */ 



/* get silence value for MuLaw data */ 
data_format = ADPMulaw; 

silence_value = (unsigned char )AGetSilenceValue (audio, data_f ormat, 
fcsignif icant_bytes, fcstatus); a. 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetSilenceValue( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

AGetSystemChannelGain - get system or monitor audio channel gain 

SYNOPSIS 

#include <audio/Alib.h> 

void AGetSystemChannelGain ( 

Audi c * aud i o , 

ASystemGainType gain_type, 

AChType channel, 

AGainDB *gain_return, 

long *status_return 
); 

DESCRIPTION 

AGetSystemChannelGain ( ) returns the current monitor or system gain. 

audio Audio structure associated with this connection. 

gainjype Type of operation: ASGTPlay, ASGTRecord, or ASGTMonitor. If this field is set to 

ASGTMonitor, the channel specification must be ACTMono. 

channel Type of channel: ACTMono, ACTLeft, or BR ACTRight . If gainjype is ASGTMonitor, 

this field must be ACTMono. 

gainjreturn Receives the returned gain value. 

status_return Receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn. 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example gets the system monitor gain: 

Audio *audio; /* audio connection */" 
ASystemGainType *sgtype; /* type of operation 
AChType * chtype; /* type of channel 
AGainDB chgain_ret; /* gain value*/" 
long status; /* error status */" 



/* get monitor gain */ 

sgtype = ASGTMonitor 

chtype = ACTMono 

ASetSystemChannelGain( audio, sgtype, chtype, &chgain_ret, fcstatus) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetSystemChannelGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGMGainRestricted(3X), AInputChannels(3X), AInputSources(3X), 
AMaxInputGain(3X), AMaxOutputGain(3X), AMinInputGain(3X), AMinOutputGain(3X), 

AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), ASetGain(3X), 

ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 
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NAME 

AGetTransStatus - get status of specified transaction 

SYNOPSIS 

#include <audio/Alib.h> 

void AGetTransStatus ( 
Audio *audio, 
ATransID xid, 

ATransStatus *trans_status_return / 
long *status_return ) ; 

DESCRIPTION 

AGetTransStatus ( ) gets the status of the transaction specified inxid. 

audio specifies the Audio structure associated with this connection. 

xid specifies the ID of the transaction. 

trans _status_return receives the returned status value. 

status_return receives the returned status of the operation unless it is set to NULL. If set to NULL, 

the transaction status is returned as an AETTransStatus event which can be read 
by ANextEvent ( ) , ACheckEvent ( ) , or ACheckMaskEvent ( ) 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status jreturn. 

AENoError 
2 AEBadAudio 
15 AEBadTransactionID 

EXAMPLES 

The following example gets the status for the xid transaction and sets up transjstat to receive the transac- 
tion status and status to receive an error status. 

Audio *audio; /* audio connection */ 

ATransStatus trans_stat; /* transaction status return */ 

long status; /* error status */ 



/* get status for xid returned from prior call */ 
AGetTransStatus (audio, xid, &trans_stat, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGetTransStatus ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

AGMGainRestricted - find out if audio controller restricts gain entries 

SYNOPSIS 

ttinclude <audio/Alib.h> 

Boolean AGBGainRestricted (Audio *audio) ; 

DESCRIPTION 

AGBGainRestricted ( ) returns TRUE if gain is restricted to AUnityGain or AZeroGain. It returns 
FALSE if other values can be used for gain entries. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon succesful completion, AGBGainRestricted ( ) returns TRUE if the audio controller restricts gain 
entries to AUnityGain or AZeroGain. It returns FALSE if other values can be used for gain entries. 

ERRORS 

AGBGainRestricted ( ) does not return an error status. 

EXAMPLES 

The following example queries the audio controller to see if gain entries are restricted: 

Boolean restricted; /* gain restricted */ 
Audio *audio; /* audio connection */ 



/* find out if gain values are restricted */ 
restricted=AGMGainRestricted (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGMGainRestricted ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AInputChannels(3X), 

AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 



HP-UX Release 9.0: August 1992 - 1 - 319 



AGrabServer(3X) Series 700 Only AGrabServer(3X) 



NAME 

AGrabServer - acquire exclusive use of audio server 

SYNOPSIS 

ttinclude <audio/Alib.h> 

Boolean AGrabServer (Audio *audio, long *status_return) ; 

DESCRIPTION 

AGrabServer ( ) acquires exclusive use of the audio server for this connection and returns TRUE unless 
the server has already been grabbed, in which case it returns FALSE. When the server is grabbed, all 
requests from other connections are interrupted; they are resumed when the server is released. To release 
(ungrab) the server, call AUngrabServer ( ) . 

audio specifies the Audio structure associated with this connection. 

statusjreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AGrabServer ( ) returns TRUE; if the server is already grabbed, the return 
is FALSE. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return. 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example grabs the server for the connection associated with audio and sets up status to 
receive an error status. 

Boolean grab; /* server acquired */ 
Audio *audio; /* audio connection */ 
long status; /* error status */ 



/* grab server for audio connection */ 
grab = AGrabServer (audio, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AGrabServer ( ) was developed by HP. 

SEE ALSO 

AUngrabServer(3X). 

Using the Audio Application Program Interface. 
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NAME ■ 

AInputChannels - get list of A/D input channels on current hardware H 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AInputChMask AInputChannels (Audio *audio) ; 

DESCRIPTION 

AInputChannels ( ) returns a mask showing the Analog and/or Digital input channels that exist on the 
current hardware. Each bit in the returned AInputChMask correponds to one input channel. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AInputChannels ( ) returns a mask showing the input channels that exist 
on the current hardware: mono, left, or right input. Each bit in the returned AInputChMask correponds 
to one type of input channel. 

ERRORS 

AInputChannels ( ) does not return an error status. 

EXAMPLES 

The following example gets the types of input channels that exist on the current hardware. 

AInputChMask in_channels; /* mask showing existing input channels */ 
Audio *audio; /* audio connection */ 



/* get input channels */ 
in_channels = AInputChannels (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AInputChannels ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AInputSources - get types of input sources existing on current hardware 

SYNOPSIS 

#include <audio/Alib.h> 

AInputSrcMask AInputSources (Audio *audio) ; 

DESCRIPTION 

AInputSources ( ) returns a mask showing the types of input sources that exist on the current 
hardware. Each bit in the returned AInputSrcMask correponds to one type of input source. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AInputSources ( ) returns a mask showing the types of input sources that 
exist on the current hardware: mono, left, or right microphone input jacks, and mono, left, or right auxili- 
ary input jacks. Each bit in the returned AInputSrcMask correponds to one type of input source. 

ERRORS 

AInputSources ( ) does not return an error status. 

EXAMPLES 

The following example gets the types of input source that exist on the current hardware. 

AInputSrcMask sources; /* input source mask */ 
Audio *audio; /* audio connection */ 



/* get input sources */ 
sources = AInputSources (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AInputSources ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AMaxInputGain(3X), AMaxOutputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

almanac() - return numeric date information in MPE format 

SYNOPSIS 

void almanac ( 

unsigned short int date, 

unsigned short int err [2], 

short int *pyear, 

short int *pmonth, 

short int *pday, 

short int *pweekday 
); 

DESCRIPTION 

almanac ( ) returns numeric date information for a date in the packed date format returned by the 
calendar () routine (see calendar (3X)). The returned information is: 

year of the century 
month of the year 
day of the month 
day of the week 

The arguments to almanac ( ) are used as follows: 



date 



An unsigned short containing the date about which information is to be returned. The year 
of the century is packed into bits through 6, and the day of the year is packed into bits 7 
through 15. The packed date format is: 



Bits 



15 



Year of Century 


Day of Year 



err The first element of this array contains the error number. The second element is always 

zero. If the call is successful, both elements contain zero. 

Error # Meaning 

1 No parameters are present in which to return values: pday, pmonth, pyear, and 
pweek all point to zero. 

2 Day of the year is out of range. 

3 Year of the century is out of range. 

pyear A pointer to a short in which the year of the century is returned. 

pmonth A pointer to a short in which the month of the year is returned (for example, January is 

represented by 1 and December is represented by 12). 

pday A pointer to a short in which the day of the month is returned. 

pweekday A pointer to a short in which the weekday is returned. 

Note that 1 is returned for Sunday and 7 for Saturday. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Refer to hpnls(5) for information about Native Language Sup- 
port routines used in C programs in the HP-UX NLS environment. 

AUTHOR 

almanac ( ) was developed by HP. 

SEE ALSO 

calendar(3X), nlfmtdate(3X), ctime(3C), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

ALoadAFile - copy audio file into new sound bucket with data conversion 

SYNOPSIS 

ttlnclude <audio/Alib.h> 

SBucket * ALoadAFile ( 

uuxw auuxw/ 

char *pathname, 
APilePormat file_format, 
AudioAttrMask attr_mask, 
Audi oAt tributes *sb_attributes, 

long *status_return 

\ . 
/ / 

DESCRIPTION 

ALoadAFile ( ) copies the audio data in pathname into a new sound bucket and returns the pointer to the 
sound bucket. The data is converted according to the specified attributes. The HP-UX kernel configuration 
sets a data size restriction. If the audio data file exceeds this size, the function returns a Out Of Memory 
error. 

When the sound bucket is no longer needed, call ADestroySBucket ( ) to deallocate the space. 

audio is the audio structure associated with this connection. 

pathname specifies the file containing the audio data. 

filejbrmat must be set to a valid enumerated value, or else an error is returned. 

If this parameter is set to AFFUnknown, the conversion utility checks for an exten- 
sion on pathname . Extensions can be appended to the filename as follows: 

name.sampling_rate.file_type. 

Valid sampling rate extensions are . n and . nk. where . nk is typically 8k to 22k. 

Valid file type extensions are: 

. u Mulaw 

.al Alaw 

.au Sun(NeXT) 

.wav Riff 

. snd NeXT 

.116 Linear 16 

. 1 8 Linear8 

. lo8 Linear80ffset 

If no recognizable extension exists, the utility checks the header on the pathname file. If file format is 
not valid or is not determinable, an error is returned. 

If you have a "Mac" file, try treating it as a raw data file in Linear8 Offset with a sampling rate of 22k 
or another sampling rate. 

attrjnask specifies the audio attributes to associate with the new sound bucket. The mask is a bit- 

wise inclusive OR of values defined in AudioAttrMask. 

If this value is set to or if sbjxttributes is set to NULL, the pathname attributes are used if 
the controller supports them. If there is an unsupported attribute, the attribute returned 
by ABestAudioAttributes ( ) is used. 

If the mask is set, the new attributes are used without checking for controller support. This 
allows ALoadAFile () to be used purely for conversion purposes. 

NOTE: If ASDurat ionMask is set, the pathname audio data is truncated or padded with 
zeros to match the length specified in 

audio_attributes . sampled_attr .duration. 

sbjxttributes specifies the attributes that are affected by the mask. Audio type must be set, separate 
from the mask. If the attribute is different from the one used by pathname, the data is 
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converted. 
status_return receives the returned status of the operation unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ALoadAFile ( ) returns a pointer to the new sound bucket. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

6 AEBadFileFormat 

7 AEBadDataFormat 

8 AEFileNotFound 
11 AEBadFileHdr 

16 AECantDetermineFormat 

17 AEOutOfMemory 

EXAMPLES 

The following example copies the file /myhome/a_dir/a_f lie into the new sound bucket and specifies 
AFPRawALaw for the file format. Specifying zero for ajnask and NULL for myAttr means that the path- 
name attributes will be used if the controller supports them; if there is an unsupported attribute, the attri- 
bute returned by ABestAudioAttributesO will be used: 

SBucket *sb; /* sound bucket*/ Audio *audio; /* audio connection */ 
char a_name[30]; /* file name */ AFllePormat file_fmt; /* file format 
*/ AudioAttrMask a_mask; /* audio attributes mask*/ AudioAt tributes 
♦myAttr; /* audio attributes */ long status; /* error status */ 

/* load file into new sound bucket */ a_name 
= "/myhome/a_dir/a_file"; file_fmt = AFFRawALaw; a_mask = 0; myAttr = 
""; sb = ALoadAFile (audio, a_name, file_fmt, ajnask, myAttr, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ALoadAFile ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), AGetSBucketData(3X), APlaySBucket(3X), 

APutSBucketData(3X), ARecordAData(3X), ASaveSBucket(3X). 

Using the Audio Application Program Interface. 
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NAME 

AMaskEvent - get first matching event in audio event queue 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AMaskEvent ( 

A.-.3J — •*, .3 J . 
uuiu -auuiu, 

AEventMask event_mask, 
AEvent *event_return, 
long *status_return ) ; 

DESCRIPTION 

AMaskEvent ( ) dequeues and returns the first event in the queue that matches the mask. If no match is 
found, AMaskEvent ( ) blocks until a matching event is received. This behavior is unlike ACheck- 
MaskEvent ( ) which does not block and returns FALSE immediately if no match is found. 

audio is the Audio structure associated with this connection. 

eventjnask is the mask specifying what type(s) of event to look for. 

event j-eturn is the first event found in the queue. 

status_return receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the event mask to select errors and transaction started events, and sets up 
event _return to receive event data and status _return to receive status data. 

Audio *audio; /* audio connection */ 
AEventMask emask; /* event mask */ 
AEvent event_return; /* event return */ 
long status; /* error status */ 



/* check event queue for mask match */ 
emask = (AErrorMaskl ATransStartedMask) ; 
AMaskEvent (audio, emask, &event_return, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AMaskEvent ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), ANextEvent(3X), APeekEvent(3X), 
APutBackEvent(3X), AQlength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface. 
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NAME 

AMaxInputGain - get maximum input gain supported by audio controller 

SYNOPSIS 

#include <audio/Alib.h> 

AGainDB AMaxInputGain (Audio *audio) ; 

DESCRIPTION 

AMaxInputGain ( ) gets the maximum input gain, in decibels, supported by the audio controller associ- 
ated with the audio connection. If the application specifies a gain higher than this, the maximum sup- 
ported value is used. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AMaxInputGain ( ) returns the maximum input gain, in decibels, that the 
audio controller supports. 

ERRORS 

AMaxInputGain does not return an error status. 

EXAMPLES 

The following example gets the maximum input gain supported by the audio controller: 

AGainDB max_in; /* max input gain */ 
Audio *audio; /* audio connection */ 



/* get max input gain */ 
max_in = AMaxInputGain (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AMaxInputGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxOutputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AMaxOutputGain - get maximum output gain supported by audio controller 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AGainDB AMaxOutputGain (Audio *audio) ; 

DESCRIPTION 

AMaxOutputGain () returns the maximum output gain, in decibels, supported by the audio controller 
associated with the audio connection. If the application specifies a gain higher than this, the supported 
maximum value is used. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AMaxOutputGain ( ) returns the maximum output gain, in decibels, that 
the audio controller supports. 

ERRORS 

AMaxOutputGain does not return an error status. 

EXAMPLES 

The following example gets the maximum output gain supported by the audio controller: 

AGainDB max_out; /* max output gain */ 
Audio *audio; /* audio connection */ 



/* get max output gain */ 
max_out = AMaxOutputGain (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AMaxOutputGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMinInputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AMinlnputGain - get minimum input gain supported by audio controller 

SYNOPSIS 

^include <audio/Alib.h> 

AGainDB AMinlnputGain (Audio *audio); 

DESCRIPTION 

AMinlnputGain ( ) returns the minimum input gain supported by the audio controller associated with 
the audio connection. If the application specifies a gain lower than this, the gain is set to AZeroGain, 
which results in no sound. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AMinlnputGain ( ) returns the minimum input gain, in decibels, that the 
audio controller supports. 

ERRORS 

AMinlnputGain ( ) does not return an error status. 

EXAMPLES 

The following example gets the minimum input gain supported by the audio controller: 

AGainDB min_in; /* min input gain */ 
Audio *audio; /* audio connection */ 



/* get min input gain */ 
min_in = AMinlnputGain (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AMinlnputGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

AMinOutputGain - get minimum output gain supported by audio controller 

SYNOPSIS 

#include <audio/Alib.h> 

AGainDB AMinOutputGain (Audio *audio) ; 

DESCRIPTION 

AMinOutputGain ( ) returns the minimum output gain, in decibels, supported by the audio controller 
associated with the audio connection. If the application specifies a gain lower than this, the gain is set to 
AZeroGain, which results in no sound. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AMinOutputGain ( ) returns the minimum output gain, in decibels, that 
the audio controller supports. 

ERRORS 

AMinOutputGain ( ) does not return an error status. 

EXAMPLES 

The following example gets the minimum output gain supported by the audio controller: 

Audio *audio; /* audio connection */ 
AGainDB min_out; /* min output gain */ 



/* get min output gain */ 
min_out = AMinOutputGain (audio ) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AMinOutputGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

ANextEvent - dequeue and return first event in audio event queue 

SYNOPSIS 

#include <audio/Alib.h> 

void ANextEvent ( 

Audio *audio, 

AEvent *event_return / 

long *status_return 
); 

DESCRIPTION 

ANextEvent ( ) dequeues and returns the first event in the audio event queue. If no match is found, the 
function blocks until an event is received. (This behavior is unlike ACheckEvent ( ) and ACheck- 
MaskEvent ( ) which do not block if there is no event or matching event, respectively.) 

audio specifies the Audio structure associated with this connection. 

eventjreturn is the first event found in the queue. 

status_return receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status jretum: 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example sets up event_return to receive event data and status_return to receive an error 
status: 

Audio *audio; /* audio connection */ 
AEvent event_return; /* event return */ 
long status; /* error status */ 



/* check event queue */ 

ANextEvent (audio, &event_return, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ANextEvent ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), APeekEvent(3X), 
APutBackEvent(3X), AQlength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface. 
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NAME 

ANumDataFormats - return number of data formats supported by audio controller 

SYNOPSIS 

#include <audio/Alib.h> 

long ANumDataFormats (Audio *audio); 

DESCRIPTION 

ANumDataFormats ( ) returns the number of data formats supported by the audio controller associated 
with the connection specified by audio. 

A list of the data formats is obtained using the function ADataFormats ( ) . 

audio specifies the Audio structure associated with this connection. 

ERRORS 

ANumDataFormats ( ) does not return an error status. 

EXAMPLES 

The following example gets the number of data formats supported by the audio controller associated with 
audio . 

long dfnum; /* number of supported data formats */ 

Audio *audio; /* audio connection */ 



/* get number of data formats supported by controller */ 
dfnum = ANumDataFormats (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ANumDataFormats () was developed by HP. 

SEE ALSO 

ADataFormats(3X). 

Using the Audio Application Program Interface. 
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NAME 

ANumSamplingRates - return number of sampling rates supported by audio controller 

SYNOPSIS 

#include <audio/Alib.h> 

long ANumSamplingRates (Audio *audio); 

DESCRIPTION 

ANumSamplingRates ( ) returns the number of sampling rates supported by the audio controller associ- 
ated with the connection specified by audio. Zero is returned if sampled data is not supported by the con- 
troller. 

A list of the supported sampling rates is obtained using the function ASamplingRates ( ) . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, ANumSamplingRates ( ) returns the number of sampling rates supported 
by the audio controller associated with the connection specified by audio. 

ERRORS 

ANumSamplingRates ( ) does not return an error status. 

EXAMPLES 

The following example gets the number of sampling rates supported by the audio controller associated with 
audio. 

long srnum; /* number of supported sampling rates */ 

Audio *audio; /* audio connection */ 



/* get number of sampling rates supported by controller */ 
srnum = ANumSamplingRates (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ANumSamplingRates ( ) was developed by HP. 

SEE ALSO 

ASamplingRates(3X). 

Using the Audio Application Program Interface. 
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NAME 

AOpenAudio - open connection to specified audio server 

SYNOPSIS 

#include <audio/Alib.h> 

Audio *AOpeuAudio(char *audio_name, long *status_return) ; 

DESCRIPTION 

AOpenAudio ( ) opens a connection to the server for the specified audio controller and returns a pointer to 
an Audio structure. The audio library allocates the Audio structure to hold information that supports 
the controller. The structure acts as the information connection between the application and the server; the 
application passes the Audio pointer to subsequent audio library function calls to identify which connec- 
tion the call should affect. 

NOTE : If the audio server is not active, this function returns a NULL and sets status_return to AEOpen- 
Pailed. For this reason, the application should use status _return (not set it to NULL) and should check it 
before proceeding. 

audio_name specifies the audio controller name as a string. If audio jxame is specified NULL, the value 
of the AUDIO environment variable is used. 



The string format is hostname '.number 



where: 



hostname specifies the name of the host machine on which the audio controller is 
physically installed. 

number specifies the audio server number on that host machine. Each audio server 
services one audio controller. More than one audio controller can be 
installed in a machine. The audio servers are numbered starting with 0. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

One successful call to AOpenAudio ( ) must precede all other audio operation function calls pertaining to 
a connection. 

To close the connection, use ACloseAudio ( ) . 

EXTERNAL INFLUENCES 

If audio_name is specified NULL, the value of the AUDIO environment variable is used. 

RETURN VALUE 

Upon successful completion, AOpenAudio ( ) returns a pointer to an Audio structure. Otherwise, it 
returns a NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

1 AESystemCall 

4 AEHostNotFound 

5 AENoSuchAudioNumber 

17 AEOutOfMemory 

18 AEOpenFailed 
23 AEllbdNotStarted 

AOpenAudio ( ) does not generate error events. 

EXAMPLES 

The following example sets the audio name argument, ajiame, to NULL, causing the value of the AUDIO 
environment variable to be used; status is set up to receive an error status. 

Audio *audio; /* audio connection */ char a_name; /* audio 
name */ long status; /* error status */ 

/* open audio connection */ a_name = "" ; audio = AOpenAudio (a_name / 
fcstatus) ; 
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DEPENDENCIES ■ 

This function belongs to the Audio Library of functions that manage connections to an audio server. The | 

audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AOpenAudio ( ) was developed by HP. 

SEE ALSO 

ACloseAudio(3X). 

Using the Audio Application Program Interface. 
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NAME 

AOutputChannels - get D/A output channels existing on current hardware 

SYNOPSIS 

#include <audio/Alib.h> 

AOutputChMask AOutputChannels (Audio *audio); 

DESCRIPTION 

AOutputChannels ( ) returns a mask showing the Digital and/or Analog output channels that exist on 
the current hardware. Each bit in the returned AOutputChMask correponds to one output channel. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AOutputChannels () returns a mask showing the output channels that 
exist on the current hardware: mono, left, or right output. Each bit in the returned AOutputChMask 
correponds to one type of output channel. 

ERRORS 

AOutputChannels ( ) does not return an error status. 

EXAMPLES 

The following example gets the types of output channels that exist on the current hardware. 

AOutputChMask out_channels; /* output channel mask */ 
Audio *audio; /* audio connection */ 



/* get output sources */ 

out_channels = AOutputChannels (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AOutputChannels ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputDestinations(3X), ASetChannelGain(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME ■ 

AOutputDestinations - get types of output destinations existing on current hardware I 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AOutputDstMask AOutputDestinations (Audio *audio) ; 

DESCRIPTION 

AOutputDestinations ( ) returns a mask showing the types of output destinations that exist on the 
current hardware. Each bit in the returned AOutputDstMask correponds to one type of output destina- 
tion. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AOutputDestinations () returns a mask showing the output destina- 
tions that exist on the current hardware: mono, left, or right headphone jacks, and mono, left, or right 
internal speakers. Each bit in the returned AOutputDstMask correponds to one type of output destina- 
tion. 

ERRORS 

AOutputDestinations ( ) does not return an error status. 

EXAMPLES 

The following example gets the types of output destination that exist on the current hardware. 

AOutputDstMask dests; /* output destination mask */ 
Audio *audio; /* audio connection */ 



/* get output destinations */ 
dests = AOutputDestinations (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AOutputDestinations ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), ASetChannelGain(3X), ASetGain(3X), 
ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

APauseAudio - pause the specified audio transaction 

SYNOPSIS 

#include <audio/Alib.h> 

void APauseAudio ( 

Audio * audio, 

ATransID xid, 

ATransStatus *trans_status_return / 

long *status_return 
); 

DESCRIPTION 

APauseAudio ( ) pauses the transaction specified in xid. To continue with the operation, call 
AResumeAudio ( ) . 

While one transaction is paused, another transaction can play or record. 

To stop the transaction so that it cannot be resumed, call AStopAudio ( ) . 

audio specifies the Audio structure associated with this connection. 

xid specifies the transaction ID. 

To use APauseAudio ( ) on a series of linked transactions, specify the first transac- 
tion in the finked list. The pause affects the current transaction. A call to 
AResumeAudio ( ) resumes the transaction and continues through the linked list. 

trans _status_return receives the returned status value. Setting this argument to NULL prevents the data 
from being collected and returned, which may enhance performance. 

status jretum receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status jretum. 

AENoError 
2 AEBadAudio 
15 AEBadTransactionID 

EXAMPLES 

The following example pauses the transaction identified by xid, sets trans_stat to 0, and sets up status to 
receive an error status. 

Audio *audio; /* audio connection */" 

ATransID xid; /* transaction ID */" 

ATransStatus trans_stat_return; /* transaction status return 

long status; /* error status */" 



/* pause transaction - xid returned by prior call */ 

trans_stat =0; 

APauseAudio (audio, xid, &trans_stat_return, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

APauseAudio ( ) was developed by HP. 

SEE ALSO 

AResumeAudio(3X), AStopAudio(3X). 



338 - 1 - HP-UX Release 9.0: August 1992 



APauseAudio(3X) Series 700 Only APauseAudio(3X) 

Using the Audio Application Program Interface. 



I 



HP-UX Release 9.0: August 1992 - 2 - 339 



APeekEvent ( 3X) Series 700 Only APeekEvent ( 3X) 



NAME 

APeekEvent - return but do not dequeue first event in audio event queue 

SYNOPSIS 

#include <audio/Alib.h> 

void APeekEvent ( 

Audio *audio, 

AEvent *event_return, 

long *status_return 
); 

DESCRIPTION 

APeekEvent ( ) returns, but does not dequeue, the first event in the audio event queue. If no match is 
found, this function blocks until a matching event is received. This behavior is unlike ACheckEvent ( ) , 
ACheckMaskEvent ( ) , and ANextEvent ( ) , which dequeue an event from the queue when they return 
it, and ACheckEvent ( ) , and ACheckMaskEvent ( ) , which do not block if there is no event or match- 
ing event, respectively. 

audio specifies the Audio structure associated with this connection. 

event_return is the first event in the audio event queue. 

status jreturn receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example sets up event to receive the event copy and status_return to receive an error status. 

Audio *audio; /* audio connection */ 

AEvent event_return; /* event_return */ 
long status; /* error status */ 



/* copy first event on queue */ 
APeekEvent (audio, &event_return, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

APeekEvent ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), 
APutBackEvent(3X), AQlength(3X) ASelectInput(3X). 

Using the Audio Application Program Interface. 
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NAME ■ 

APlaySBucket - play specified sound bucket and return transaction ID I 

SYNOPSIS 

ttinclude <audio/Alib.h> 

ATransID APlaySBucket ( 

Audio ♦audio, 

SBucket *sb, 

SBP lay Pa rams *pp, 

loiiy * status return 

); 

DESCRIPTION 

APlaySBucket ( ) plays the audio data in the specified sound bucket on the specified server connection 
and returns a transaction ID. 

audio specifies the Audio structure associated with this connection. 

sb specifies the sound bucket to be played. 

pp specifies the play parameters associated with the play operation. 

status_return receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, APlaySBucket ( ) returns the transaction ID. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

10 AEBadGainMatrix 

20 AEBadSoundBucket 

EXAMPLES 

The following example plays the audio data contained in the sound bucket specified by sb and returns a 
transaction ID. 

ATransID xid; /* transaction ID */ 

Audio *audio; /* audio connection */ 

SBucket *sb; /* sound bucket*/ 

SBPlayParams *pparams; /* play parameters */ 

long status; /* error status */ 



/* play sound bucket */ 

xid = APlaySBucket (audio, sb, pparams, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

APlaySBucket ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), 

APutSBucketData(3X), ARecordAData(3X), ASaveSBucket(3X). 

Using the Audio Application Program Interface. 
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NAME 

APlaySStream - initiate transaction and return transaction ID and SStream structure 

SYNOPSIS 

ttinclude <audio/Allb.h> 

ATransID APlaySStream ( 

Audio * audio, 

AudioAttrMask attr_mask, 

AudioAttributes *audio_attributes, 

SSPlayParams *pp, 

SStream *sstreant_retum, 

long *status_retum 
\ . 

DESCRIPTION 

APlaySStream () initiates a play sound stream transaction and returns a transaction ID and an 
SStreams structure that contains a TCP socket address. 

The application connects the socket it has created to the TCP address. The play operation begins as soon as 
there is data on the sound stream. The play stream transaction can be controlled using APauseAudlo ( ) , 
AResumeAudio ( ) , and AStopAudlo ( ) . 

audio specifies the Audio structure associated with this connection. 

attr_mask specifies which elements of the audiojxttributes structure to use; it is the bitwise inclusive 

OR of the valid audio attribute masks. 

If attr_mask is zero, the values in the AudioAttributes structure returned by ABes- 
tAudioAt tributes ( ) are used. 

audiojxttributes 

contains values for type and sampled attributes. Type must be set, separate from the 
mask. 

If audiojxttributes is NULL, the values in the AudioAttributes structure returned by 
ABestAudioAttributes ( ) are used; values in this structure are also used for 
unspecified attributes. 

pp is the pointer to the play parameters associated with the play operation. 

status _return receives the returned status of the operation unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, APlaySStream( ) returns a transaction ID. 

ERRORS 

If status j-eturn is not set to NULL, one of the following is returned in status j-eturn: 

AENoError 

2 AEBadAudio 

7 AEBadDataFormat 

10 AEBadGainMatrix 

13 AEBadAttribute 

EXAMPLES 

The following example starts a play stream transaction and sets up sstream to receive the SStream struc- 
ture and status to receive an error status return. 

ATransID xid; /* trans ID */ 

Audio *audlo; /* audio connection */ 

AudioAttrMask a_mask; /* audio attribute mask */ 

AudioAttributes *attribs; /* audio attributes*/ 

SSPlayParams ss_pp; /* sstream play parameters */ 

SStream sstream; /* sstream structure */ 

long status; /* error status */ 
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/* play sstream */ 

xid = APlaySSt ream (audio, a_mask, attribs, ss_pp, &sstream, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

APlaySSt ream ( ) was developed by HP. 

SEE ALSO 

AConnectRecordSStreamO, ARecordSStream(). 

Using the Audio Application Program Interface. 



HP-UX Release 9.0: August 1992 - 2 - 343 



AProtocolRevision(3X) Series 700 Only AProtocolRevision(3X) 



NAME 

AProtocolRevision - get minor revision number of protocol used by audio server 

SYNOPSIS 

#include <audio/Alib.h> 

long AProtocolRevision (Audio *audio) ; 

DESCRIPTION 

AProtocolRevision( ) returns the minor revision number of the protocol used by the audio server for 
the connection specified by audio . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AProtocolRevision ( ) returns the minor revision number of the protocol 
for the audio server associated with this connection. 

ERRORS 

AProtocolRevision( ) does not return an error status. 

EXAMPLES 

The following example returns the minor revision number of the protocol associated with the audio server 
for the connection specified by audio . 

long p_rev; /* minor protocol revision */ 
Audio *audio; /* audio connection */ 



/* get minor protocol revision */ 
p_rev = AProtocolRevision (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AProtocolRevis ion ( ) was developed by HP. 

SEE ALSO 

AProtocolVersion(3X), AServerVendor(3X), AVendorRelease(3X). 

Using the Audio Application Program Interface. 
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NAME 

AProtocolVersion - get major version number of protocol used by audio server 

SYNOPSIS 

#include <audio/Alib.h> 

long AProtocolVersion (Audio *audio) ; 

DESCRIPTION 

AProtocolVersion ( ) returns the major version number of the protocol used by the audio server for the 
connection specified b v audio , 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AProtocolVersion( ) returns the major version number of the protocol 
for the audio server associated with this connection. 

ERRORS 

AProtocolVersion ( ) does not return an error status. 

EXAMPLES 

The following example returns the major version number of the protocol associated with the audio server 
for the connection specified by audio . 

long p_version; /* major protocol version */ 
Audio *audio; /* audio connection */ 



/* get major protocol version */ 
p_version = AProtocolVersion (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AProtocolVersion ( ) was developed by HP. 

SEE ALSO 

AProtocolRevision(3X), AServerVendor(3X), AVendorRelease(3X). 

Using the Audio Application Program Interface. 
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NAME 

APutBackEvent - push event onto head of audio event queue 

SYNOPSIS 

#include <audio/Alib.h> 

void APutBackEvent ( 

Audio *audlo, 

AEvent * event , 

long *status_return 
); 

DESCRIPTION 

APutBackEvent ( ) pushes event onto the head of the audio event queue for the server specified by audio. 

audio specifies the Audio structure associated with this connection. 

event is the event to put on the queue. 

status_return receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status setum: 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example puts event at the head of the audio event queue and sets up status jreturn to receive 
an error status. 

Audio *audio; /* audio connection */ 

AEvent * event; /* event */ 

long status; /* error status */ 



/* put event at head of queue */ 

event = event_return; /* use event_return value from prior call */ 

APutBackEvent (audio, event, &status) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

APutBackEvent ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), 
APeekEvent(3X), AQLength(3X), ASelectInput(3X). 

Using the Audio Application Program Interface . 
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NAME ■ 

APutSBucketData - copy audio data from buffer to sound bucket I 

SYNOPSIS 

#include <audio/Alib.h> 

unsigned long APutSBucketData ( 

Audio * audio, 
SBucket *sb, 

unsigned long start_of f set, 

char *buffer, 

unsigned long length, 

long *status_return 
); 

DESCRIPTION 

APutSBucketData ( ) copies the data from a buffer to a sound bucket. 

audio specifies the Audio structure associated with this connection. 

sb specifies the sound bucket to receive the data. 

start jyffset specifies where to start writing the copied data, given as the byte offset from the beginning 

of the sound bucket. 

buffer specifies the buffer containing the data to copy. 

length specifies the length of the data in the buffer, in bytes. 

statusjretum receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, APutSBucketData ( ) returns the byte count of the copied data. 

ERRORS 

If statusjretum is not set to NULL, one of the following is returned in statusjretum: 

AENoError 
2 AEBadAudio 
20 AEBadSoundBucket 

EXAMPLES 

The following example copies the audio data from the buffer buff to the sound bucket sb and returns the 
number of bytes that were copied. The data is placed starting at the beginning of the sound bucket (offset 
0). In this example, we assume that we are returning data from the buffer at bufp that was written there 
by AGetSBucketData ( ) . We use the datalenjg value returned by AGetSBucketData ( ) as the 
length of the data. 

unsigned long datalen_p; /* copied data length */ 
Audio *audio; /* audio connection */ 

SBucket *sb; /* sound bucket*/ 

unsigned long startoff; /* start offset */ 
char *bufp; /* ptr to buffer */ 

long status; /* error status */ 



/* copy data from buffer to sb */ 

startoff = 0; 

datalen_p = APutSBucketData (audio, sb, startoff, bufp, datalen_g, fcstatus) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 
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AUTHOR 

APut SBucketDat a ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), APlaySBucket(3X), 
ARecordAData(3X), ASaveSBucket(3X). 
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NAME 

AQLength - return number of events on audio event queue 

SYNOPSIS 

#include <audio/Alib.h> 

int AQLength (Audio *audio); 

DESCRIPTION 

AQLength ( ) returns number of events on the audio event queue for the audio server connection specified 
by audio . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AQLength ( ) returns the number of events on the audio event queue for the 
audio connection. 

ERRORS 

AQLength ( ) does not return an error status. 

EXAMPLES 

The following example gets the number of events on the audio event queue. 

int e_num; /* number of events */ 
Audio *audio; /* audio connection */ 



/* get number of events on queue */ 
e_num = AQLength ( audio ) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AQLength ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), 
APeekEvent(3X), APutBackEvent(3X), ASelectInput(3X). 

Using the Audio Application Program Interface . 
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NAME 

AQueryAFile - get file format of specified file 

SYNOPSIS 

#include <audio/Alib.h> 

AFilePormat AQueryAFile (Audio *audio, char *name, long *status_return) ; 

DESCRIPTION 

AQueryAFile ( ) returns the file format of the file specified in name. 

audio specifies the Audio structure associated with this connection. 

name is the pathname of the audio data file to be queried. 

status_return receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AQueryAFile () returns the file format of the file specified in name. 
AFFUnknown is returned if the format type cannot be determined. 

ERRORS 

If status jretum is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

2 AEBadAudio 

8 AEFileNotFound 

16 AECantDetermineFormat 

EXAMPLES 

The following example queries the file format of the file /myhome/a_dir/a_f ile: 

ift .ft 4 AFileFormat file_fmt; /* file format */ Audio *audio; /* audio connection */ long status; 

/* status */ . . . /* load file into new sound bucket */ charfnamef] = 

7myhome/a_dir/a_file"; file_fmt = AQueryAFile( audio, fname, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AQueryAFile ( ) was developed by HP. 

SEE ALSO 

AGetAFileAttributesO Using the Audio Application Program Interface. 
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I 



NAME 

ARecordAData - read audio data into sound bucket 



SYNOPSIS 

ttinclude <audio/Alib.h> 

ATransID ARecordAData ( 

Audio * audio, 

SBucket *sb, 

SBRecordParams *rp, 

long *status_return 
); 

DESCRIPTION 

ARecordAData ( ) reads audio data from the specified server connection into the specified sound bucket 
and returns a transaction ID. ARecordAData ( ) does not block until the record is complete, and so it 
can not be followed immediately by a call to ASaveSBucket ( ) . See ASaveSBucket (3X) for suggested pro- 
gram actions. 

audio specifies the Audio structure associated with this connection. 

sb specifies the sound bucket to receive the data. 

rp specifies the record parameters associated with the record operation. 

status_return receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ARecordAData ( ) returns the transaction ID. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

2 AEBadAudio 

10 AEBadGainMatrix 

20 AEBadSoundBucket 

EXAMPLES 

The following example reads data from the connection associated with audio into the sound bucket specified 
by sb and returns a transaction ID. 

TransID xid; /* transID */ 

Audio *audio; /* audio connection */ 

SBucket *sb; /* sound bucket*/ 

SBRecordParams rparams; /* record parameters */ 
long status; /* error status */ 



/* start record transaction */ 

xid = ARecordAData (audio, sb, &rparams, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ARecordAData ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), APlaySBucket(3X), 
APutSBucketData(3X),ASaveSBucket(3X). 

Using the Audio Application Program Interface. 
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NAME 

ARecordSStream - initiate transaction; return transaction ID and SStreams structure 

SYNOPSIS 

#include <audio/Alib.h> 

ATransID ARecordSStream ( 
Audio * audio 
AudioAttrMask attr_mask, 
AudioAttributes *audio_attributes, 
SSRecordParams *rp, 
SStream *sstream_return, 

long *status_retum 

\ . 

/ 1 

DESCRIPTION 

ARecordSStream () initiates a sound stream record transaction and returns a transaction ID and an 
SStream structure that contains a TCP socket address. 

The application connects the socket it has created to the TCP address. The record operation begins immedi- 
ately or in pause mode, depending on the pause_first field in SSRecordParams. The record stream tran- 
saction can be controlled using APauseAudio ( ) , AResumeAudio ( ) , and AStopAudio ( ) . 

audio specifies the Audio structure associated with this connection. 

attr_mask specifies which elements of the audio jxttributes structure to use; it is the bitwise inclusive 

OR of the valid audio attribute masks. 

liattrjnask is zero, the values in the. AudioAttributes structure returned by ABes- 
tAudioAt tributes ( ) are used. 

audiojxttributes 

contains values for type and sampled attributes. Type must be set, separate from the 
mask. 

If audiojxttributes is NULL, the values in the AudioAttributes structure returned by 
ABestAudioAttributes () are used; values in this structure are also used for 
unspecified attributes. 

rp specifies the record parameters associated with the record operation. 

sstream _return receives the returned SStream structure. 

status_return receives the returned status of the operation unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ARecordSStream ( ) returns a transaction ID. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

7 AEBadDataFormat 

10 AEBadGainMatrix 

13 AEBadAttribute 

EXAMPLES 

The following example starts a record stream transaction, setting up sstream to receive the SStream 
structure and status to receive an error status return. 

ATransID xid; /* transID */ 

Audio *audio; /* audio connection */ 

AudioAttrMask a_mask; /* audio attribute mask */ 

AudioAttributes attribs; /* audio attributes*/ 

SSRecordParams ss_rp; /* sstream record parameters */ 

SStream sstream; /* sstream structure */ 

long status; /* error status */ 
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/* record sstream */ 

xid = ARecordSSt ream (audio, a_mask, fcattribs, &ss_rp, &sstream, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ARecordSSt ream ( ) was developed by HP. 

SEE ALSO 

AConnectRecordSStream(), APlaySStream(). 

Using the Audio Application Program Interface. 
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NAME 

AResumeAudio - resume specified audio transaction 

SYNOPSIS 

#include <audio/Alib.h> 

void AResumeAudio ( 

Audio *audio, 

ATransID xid, 

ATransStatus *trans_status_return / 

long *status_return 
); 

DESCRIPTION 

AResumeAudio ( ) resumes the specified transaction if the transaction was paused by APauseAudio ( ) . 

audio specifies the Audio structure associated with this connection. 

xid specifies the transaction ID. 

To use AResumeAudio ( ) on a paused series of linked transactions, specify the first 
transaction in the linked list. The resume affects the current (paused) transaction. 

trans _status_return receives the returned status value. Setting this argument to NULL prevents the data 
from being collected and returned, which may enhance performance. 

status jretum receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return: 

AENoError 
2 AEBadAudio 
15 AEBadTransactionID 

EXAMPLES 

The following example resumes the transaction identified by xid, sets trans_stat to NULL, and sets up status 
to receive an error status. 

Audio *audio; /* audio connection */ 
ATransID xid; /* transaction ID */ 
long status; /* error status */ 



/* resume transaction - xid returned from prior call */ 
AResumeAudio (audio, xid, NULL, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AResumeAudio ( ) was developed by HP. 

SEE ALSO 

APauseAudio(3X), AStopAudio(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASamplingRates - return array of sampling rates supported by audio controller 

SYNOPSIS 

#include <audio/Alib.h> 

unsigned long* ASamplingRates (Audio *audio); 

DESCRIPTION 

ASamplingRates ( ) returns a pointer to an array of sampling rates supported by the audio controller 
associated with the audio connection. 

The number of sampling rates in the array is obtained using the function ANumSampl ingRat es ( ) . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, ASamplingRates ( ) returns a pointer to an array of sampling rates sup- 
ported by the audio controller associated with the connection specified by audio . 

ERRORS 

ASamplingRates ( ) does not return an error status. 

EXAMPLES 

The following example returns an array containing the sampling rates supported by the audio controller 
associated with audio . 

unsigned long *s_rates / first_rate; /* supported sampling rates */ 
Audio *audio; /* audio connection */ 



/* get pointer to array of sampling rates */ 
s_rates = ASamplingRates (audio) ; 
/* get first sampling rate */ 
first_rate = s_rates[0]; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASamplingRates ( ) was developed by HP. 

SEE ALSO 

ANumSamplingRates(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASaveSBucket - write sound bucket data into file with data conversion 

SYNOPSIS 

#include <audio/Alib.h> 

void ASaveSBucket ( 

AudxG * audio, 

SBucket *sb, 
char * pathname, 
APilePormat file_format, 
AudioAttrMask attr_mask, 
Audi oAt tributes *target_attributes, 
ATime *offset, 
AWriteMode mode, 
long *status_return 
); 

DESCRIPTION 

ASaveSBucket ( ) writes the data in sb into the file specified by pathname after making conversions 
according to the specified attributes. 

ARecordAData ( ) does not block until the record operation is complete, so calling ASaveSBucket ( ) 
immediately after ARecordAData ( ) usually results in an error. To avoid the error, the application pro- 
gram can set up its own wait loop, or wait on a transaction-stopped or transaction-completed event. See the 
program /usr/audio/examples/recorder .c for an example of waiting either for a transaction- 
stopped event or for the user to terminate the record operation by pressing [Return]. 

When the sound bucket is no longer needed, call ADestroySBucket ( ) to deallocate the space. 



audio 
sb 

pathname 
filejbrmat 



attr mask 



is the audio structure associated with this connection. 

is the sound bucket that contains the audio data and associated attributes. 

specifies the file to receive the data. If the file does not exist, it is created. 

specifies the file format to use for the write. If this parameter is not set to a valid 
enumerated value, an error is returned. 

If this parameter is set to APPUnknovm, the conversion utility checks for an exten- 
sion on pathname. Extensions can be appended to the filename as follows: 

name.sampling_rate.file_type. 

Valid file type extensions are: 

. u Mulaw 

.al Alaw 

.au Sun(NeXT) 

.wav Riff 

. snd NeXT 

.116 Linear 16 

. 1 8 Linear8 

.lo8 Linear80ffset 

If no recognizable extension exists and pathname is an existing file, the utility checks 
the header on the existing file. If there is no determinable file format, an error is 
returned; there is no default. 

If this parameter specifies a different format than the one indicated by an existing file 
in pathname, (unless mode is AWMTruncateAppend and offset is 0), an error is 
returned. 

specifies the audio attributes to associate with the data written to the file; conversion 
occurs where necessary. The mask is a bitwise inclusive OR of the values defined in 
AudioAttrMask. This mask is cleared if target jxttributes is set to NULL. 
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When a mask bit is set to and pathname is an existing file, the conversion utility 
checks the existing file type in the file header and uses a value that is compatible with 
it. 

When a mask bit is set to and pathname is not an existing file, the conversion utility 
checks the file type indicated by the pathname extension, if any, and uses a value that 
is compatible with it. If no value can be determined, the sound bucket value for the 
attribute is used. 

When a mask bit is set to 1 and pathname is not an existing file, the specified attri- 
bute is checked for compatibility with the existing file. An error is returned if there is 
a discrepancy. 

When a mask bit is set to 1 and a file does not exist in pathname, the specified attri- 
bute is used. 

NOTES: If ASDurationMask is set, the sound bucket data is truncated or padded 
with zeros to match the length specified in 

audio_attributes . sampled_attr .duration. 

If ASSamplingRateMask is set, it is used without checking the file name exten- 
sion. If sampling _rate is not specified, the file name is checked for an extension. Sam- 
pling rate attributes can be specified in a filename extension as follows: 

name . sampling j ate .filejype 

Valid sampling rate extensions are .n and .nk where .nk. is typically 8k to 22k. 

target _attributes specifies the attributes that are affected by the mask. If set to NULL, attrjnask is 
cleared and attributes are determined according to compatibility with pathname and 
sb (see attrjnask). Audio type must be set (separate from the mask). 

offset specifies where to begin writing in the destination file, given in ATimeType units 

(ATTSamples, ATTMilliSeconds, or ATTFu 11 Length) from the beginning of 
the audio data, excluding the header. 

If pathname is not an existing file and offset is not 0, the new file is padded with zeros 
up to the offset. 

If pathname is an existing file and offset is greater than the length of the audio data, 
zeros are appended to the audio data until its length is equal to offset. 

mode specifies how the data should be written into the file: 

AWMOverWrite specifies that data from the sound bucket sb overwrites the data in 
pathname starting at offset. Data that precedes or follows the overwritten region 
remains unchanged. If necessary, the length of the file is increased to accommodate 
the new data. 

AWMTruncateAppend specifies that the data in pathname is truncated at offset and 
the write begins at that point. If necessary, the length of the file is increased or 
decreased to accommodate the new data. 

AWMInsert specifies that data from the sound bucket sb is inserted in the file path- 
name starting at offset. The length of the file is increased to accommodate the new 
data. 

status_return receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

6 AEBadFileFormat 

7 AEBadDataFormat 

8 AEFileNotFound 
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11 AEBadFileHdr 

13 AEBadAttribute 

14 AEBadOflfset 

16 AECantDetermineFormat 

20 AEBadSoundBucket 

EXAMPLES 

The following example copies the data from sound bucket sb to existing file /myhome/a_dir/a_f ile, 
starting at offset 1668. The file format and audio attributes of the existing file are to be used, so file_fmt is 
set to AFFUnknown, NULL is passed for audio attributes, and the attribute mask is set to 0. 

The mode is set to AWMOverwrite so that data that precedes or follows the overwrite region will not be 
affected. If necessary, the length of the file will be increased to accommodate the new data. 

Audio *audio; /* audio connection */ 

SBucket *sb; /* sound bucket */ 

AFileFormat file_fmt; /* file format */ 

AudioAttrMask a_mask; /* audio attributes mask */ 

ATime startoff; /* start offset */ 

AWriteMode mode; /* write mode */ 

long status; /* error status */ 



/* save sound bucket data */ 

staticchara_name [ ] = {"/myhome/a_dir/a_f ile"}; 

file_fmt = AFFUnknown; 

a_mask = 0; 

startoff .type = ATTSamples; 

startoff .u. samples = 1668; 

mode = AWMOverwrite; /* overwrite without truncate */ 

ASaveSBucket (audio, sb, a_name, file_fmt, a_mask, NULL, fcstartoff, 

mode, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASaveSBucket ( ) was developed by HP. 

SEE ALSO 

ACreateSBucket(3X), ADestroySBucket(3X), AGetSBucketData(3X), ALoadAFile(3X), APlaySBucket(3X), 
APutSBucketData(3X),ARecordAData(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASelectlnput - request report of specified audio events 

SYNOPSIS 

void ASelectlnput ( 

Audio *audio, 

ATransID xid, 

AEventMask event_mask, 

long *status_return 
) : 

DESCRIPTION 

ASelectlnput ( ) requests the report of the audio events specified by the event mask. 

audio is the Audio structure associated with this connection. 

xid specifies the ID of the transaction whose events are of interest. 

event_mask specifies the events for which a report is requested. Each bit in the mask corresponds to 
one type of audio event. The mask is the bitwise inclusive OR of the masks for the indivi- 
dual event types. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return: 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the event mask to request record monitor and transaction pause events, and 
sets up status jreturn to receive an error status. 

Audio *audio; /* audio connection */ 

TransID xid; /* transaction ID */ 

AEventMask emask; /* event mask */ 

long status; /* error status */ 



/* request input event reports */ 

emask = ( AETRecordMonitor I AETransPaused ) 

ASelectlnput (audio, xid, emask, fcstatus) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASelectlnput ( ) was developed by HP. 

SEE ALSO 

ACheckEvent(3X), ACheckMaskEvent(3X), AEventsQueued(3X), AMaskEvent(3X), ANextEvent(3X), 
APeekEvent(3X), APutBackEvent(3X), AQlength(3X). 

Using the Audio Application Program Interface. 
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NAME 

AServerVendor - get vendor name of audio server for this connection 

SYNOPSIS 

#include <audio/Alib.h> 

char* AServerVendor (Audio *audio) ; 

DESCRIPTION 

AServerVendor ( ) returns a pointer to the name of the vendor of the audio server for the connection 
specified by audio . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AServerVendor ( ) returns a pointer to the name of the vendor of the the 
audio server associated with this connection. 

ERRORS 

AServerVendor ( ) does not return an error status. 

EXAMPLES 

The following example returns a pointer to the name of the vendor of the audio server for the connection 
specified by audio. 

char* *vendor_name ; /* server vendor name */ 
Audio *audio; /* audio connection */ 



/* get server vendor name */ 
vendor_name = AServerVendor (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AServerVendor ( ) was developed by HP. 

SEE ALSO 

AProtocolRevision(3X), AProtocolVersion(3X), AVendorRelease(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASetChannelGain - set transaction channel gain 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void ASetSystemChannelGain( 
Audio * audio, 
ATransID xid, 
AChType channel, 



); 



long *status_return 



DESCRIPTION 

ASetChannelGain ( ) sets the transaction gain to the value in gain. 

audio Audio structure associated with this connection. 

xid Transaction ID. 

channel Type of channel: ACTMono, ACTLef t, or ACTRight. 

gain Specifies the volume: AUnityGain, AZeroGain, or a number of decibels. 

status_return Receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status _return is not set to NULL, one of the following is returned in status _return. 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the transaction right channel gain to -6. 

Audio *audio; /* audio connection */ 

AChType *chtype; /* type of channel */ 

AGainDB chgain; /* gain specification*/ 

long status; /* error status */ 



/* set xid right channel gain to -6 */ 

chtype = ACTRight 

chgain = -6; 

ASetChannelGain (audio, xid, chtype, chgain, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetChannelGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), 
ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 



Using the Audio Application Program Interface. 
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NAME 

ASetCloseDownMode - set close-down mode to destroy or complete transactions on specified connection 

SYNOPSIS 

#include <audlo/Alib.h> 

void ASetCloseDownMode ( 

Audio *audic, 

ACloseDownMode close_mode, 

long *status_return 
); 

DESCRIPTION 

ASetCloseDownMode ( ) sets the close-down mode to keep or destroy active and pending transactions on 
the connection associated with audio . 

audio specifies the Audio structure associated with this connection. 

close_mode specifies one of two modes: ADestroyAll causes all active and pending transactions for 

this connection to be stopped and destroyed when the connection is closed; associated 
storage is freed immediately; AKeepTransactions prevents transactions for this con- 
nection from being destroyed and allows them to complete before the close. 

status .return receives the returned status of the operation unless it is set to NULL by the application. 

ERRORS 

If status _return is not set to NULL by the application, one of the following is returned in status jreturn: 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the close-down mode to allow transactions to complete, and sets up status to 
receive an error status. 

Audio * audio; /* audio connection */ 
ACloseDownMode close_mode; /* close down mode */ 
long status; /* error status */ 



/* set close-down mode */ 
close_mode = AKeepTransactions; 
ASetCloseDownMode (audio, close_mode # fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetCloseDownMode ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

ASetErrorHandler - replace default error handler with specified handler 

SYNOPSIS 

#include <audio/Alib.h> 

AErrorHandler ASetErrorHandler (AErrorHandler handler) ; 

DESCRIPTION 

ASetErrorHandler ( ) replaces the default error handler with the handler specified in handler, and 
returns a pointer to the handler that was previously in effect. The new error handler should return 
AENoError, if the error should be ignored. If the error should not be ignored and the handier cannot 
correct it, the handler should return the error code. 

handler is the pointer to an application-supplied handler function. 

RETURN VALUE 

Upon successful completion, ASetErrorHandler ( ) returns a pointer to the handler that was previ- 
ously in effect. 

ERRORS 

ASetErrorHandler ( ) does not return an error status. 

EXAMPLES 

The following example replaces the default error handler with a handler named myhandler. 

long myhandler ( 

Audio *audlo, 

AErr or Event *err_event 
) 
{ 

char errorbuff [132] ; 

AGetErrorText (audio, err_event->error_code, errorbuff, 131); 
printf ("Error is %s\n" , errorbuff); 
return (err_event->error_code) ; 
} 



AErrorHandler prev_handler; /* ptr to previous handler */ 
AErrorHandler myhandler; /* this data type is a function*/ 



/* replace default error handler */ 
prev_handler = ASetErrorHandler (myhandler) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetErrorHandler ( ) was developed by HP. 

SEE ALSO 

ASetIOErrorHandler(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASetGain - set play volume or record gain of specified transaction 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void ASetGain ( 

Audio *audio, 

ATransID xid, 

AGainDB gain, 

long *status_return 
); 

DESCRIPTION 

ASetGain ( ) sets the play volume or record gain of the transaction specified in xid. 

audio specifies the Audio structure associated with this connection. 

xid specifies the ID of the transaction that was returned by ACreateSBucket ( ) or 

ALoadAPileO. 

gain specifies the new values for the play volume or record gain. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jretum is not set to NULL, one of the following is returned in status j-eturn. 

AENoError 
2 AEBadAudio 
15 AEBadTransactionID 

EXAMPLES 

The following example sets the gain for the xid transaction to be AUnityGain (unchanged) and sets up 
status to receive an error status: 

Audio *audio; /* audio connection */ 

ATransID xid; /* transaction ID */ 

AGainDB gain; /* gain */ 

long status; /* error status */ 



/* set gain for xid returned from prior call */ 

gain = AUnityGain; 

ASetGain (audio, xid, gain, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), 
ASetChannelGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASetlOErrorHandler - replace default I/O error handler with specified handler 

SYNOPSIS 

# include <audio/Alib.h> 

AIOErrorHandler ASetlOErrorHandler (AIOErrorHandler handler) ; 

DESCRIPTION 

ASetlOErrorHandler ( ) replaces the default I/O error handler with the handler specified in handler, 
and returns a pointer to the handler that was previously in effect. When the new handler exits via return, 
the application program exits. 

handler is the pointer to an application-supplied I/O handler function. 

RETURN VALUE 

Upon successful completion, ASetlOErrorHandler ( ) returns a pointer to the handler that was previ- 
ously in effect. 

ERRORS 

ASetlOErrorHandler ( ) does not return an error status. 

EXAMPLES 

The following example replaces the default I/O error handler with a handler named myjojiandler. 

long my_lo_handler (Audio *audio) { 

printf ("An I/O Error Occurred ! \n" ) ; 

return 0; } . . . AIOErrorHandler 

prev_io_handler; /* ptr to previous handler */ AIOErrorHandler 
my_io_handler; /* this data type is a function*/ 

/* replace default I/O error handler */ prev_io_handler = 
ASetlOErrorHandler (iay_io_handler) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetlOErrorHandler ( ) was developed by HP. 

SEE ALSO 

ASetErrorHandler(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASetSystemChannelGain - set system or monitor audio channel gain 

SYNOPSIS 

#lnclude <audlo/Alib.h> 

void ASetSystemChannelGain ( 

Audio *audio, 

ASystemGainType gain_type, 

AChType channel, 

AGainDB gain, 

long *status__return 
); 

BESCREPTION 

ASetSystemChannelGain ( ) sets the system gain to the value ingain. If gainjype is ASGTMonitor, 
the setting controls how much of the record input signal is fed to the internal speaker or auxiliary output. 
This ability to monitor the input is particularly useful when the recording input is not from a microphone. 

audio Audio structure associated with this connection. 

gainjype Type of operation: ASGTPlay, ASGTRecord, or ASGTMonitor. If this field is set to 

ASGTMonitor, the channel specification must be ACTMono. 

channel Type of channel: ACTMono, ACTLeft, or ACTRight. If gainjype is ASGTMonitor, 

this field must be ACTMono. 

gain Specifies the volume: AUnityGain, AZeroGain, or a number of decibels. 

status_return receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn. 

AENoError 

2 AEBadAudio 

3 AEBadValue 

EXAMPLES 

The following example sets the gain on the monitor to -6. 

Audio *audio; /.* audio connection */ 

ASystemGainType *sgtype; /* type of operation */ 

AChType *chtype; /* type of channel */ 

AGainDB chgain; /* gain specification*/ 

long status; /* error status */ 



/* set monitor gain to -6 */ 

sgtype = ASGTMonitor 

chtype = ACTMono 

chgain = -6; 

ASetSystemChannelGain (audio, sgtype, chtype, chgain, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetSystemChannelGain ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 

AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), 
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ASetChannelGain(3X), ASetGain(3X), ASimplePlayer(3X), ASimpleRecorder(3X). 
Using the Audio Application Program Interface. 
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NAME 

ASetSystemPlayGain - set system play volume 

SYNOPSIS 

#include <audio/Alib.h> 

void ASetSystemPlayGain ( 

Audio *audio, 

AGainDB gain, 

long *status_return 
); 

DESCRIPTION 

ASetSystemPlayGain ( ) sets the system play volume to the value in gain. 

audio specifies the Audio structure associated with this connection. 

gain specifies in decibels the new value for the play volume. 

statusjreturn receives the returned status of the operation unless it is set to NULL by the application. 

ERRORS 

If status _return is not set to NULL by the application, one of the following is returned in statusjreturn. 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example sets the system play volume to -6. This reduces the play volume by a factor of 4, 
relative to AUnityGain. 

Audio *audio; /* audio connection */ 
AGainDB spvol; /* sys play vol */ 
long status; /* error status */ 



/* set system play volume */ 

spvol = -6; 

ASetSystemPlayGain (audio, spvol, fcstatus); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetSystemPlayGain ( ) was developed by HP. 

SEE ALSO 

AGetGain(3X), AGetSystemMonitorGain(3X), AGetSystemPlayGain(3X), AGetSystemRecordGain(3X), 
AGMGainRestricted(3X), AtnputChannels(3X), AInputSources(3X), AMaxInputGain(3X), 

AMaxOutputGain(3X), AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), 

AOutputDestinations(3X), ASetGain(3X), ASetSystemMonitorGain(3X), ASetSystemRecordGain(3X), 
ASimplePlayer(3X),ASimpleRecorder(3X). 

Using the Audio Application Program Interface . 
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NAME 

ASetSystemRecordGain - set system record gain 

SYNOPSIS 

#include <audio/Alib.h> 

void ASetSystemRecordGain ( 

Audio *audio, 
AGainDB gain, 
long *status_return 

); 

DESCRIPTION 

ASetSystemRecordGain ( ) sets the system record gain to the value ingain. 

audio specifies the Audio structure associated with this connection. 

gain specifies the new value for the record gain. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return. 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example sets the system record gain to -6. 

Audio *audio; /* audio connection */ 
AGainDB srgain; /* sys record gain */ 
long status; /* error status */ 



/* set system record gain */ 

srgain = -6; 

ASetSystemRecordGain (audio, srgain, fcstatus) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetSystemRecordGain ( ) was developed by HP. 

SEE ALSO 

AGetGain(3X) AGetSystemMonitorGain(3X), AGetSystemPlayGain(3X), AGetSystemRecordGain(3X), 
AGMGainRestricted(3X), AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), 

AMaxOutputGain(3X), AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), 

AOutputDestinations(3X), ASetGain(3X), ASetSystemMonitorGain(3X), ASetSystemPlayGain(3X), 
ASimplePlayer(3X),ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 



ASetupConversion - perform setup required for stream data conversion 

SYNOPSIS 

ttinclude <audio/Alib.h> 



AConve r t Par ams * 
ASetupConversion ( 

Audio 

AudioAttributes 

AByteOrder 

AudioAttributes 

AByteOrder 

long 



* audio, 

* srcjittributes, 

* src_byte_order, 

* destjuttributes, 

* dest_byte_order, 

* status_return ) ; 



DESCRIPTION 

ASetupConversion ( ) performs initialization for stream data conversion. The user specifies the source 
stream attributes and byte order and the desired destination stream attributes. ASetupConversion 
returns a pointer to an AConvertParams structure, which will be used by AConvertBuf f er to perform 
the stream conversion. 

audio specifies the Audio structure associated with this connection. 

srcjxttributes specifies the attributes of the source stream. 

src_byte_order specifies the byte ordering of the source stream. 

destjxttributes specifies the attributes of the destination stream. 

destjbytejorder specifies the byte ordering of the destination stream. 

status _return receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, ASetupConversion ( ) returns a pointer to the conversion parameter 
structure AConvertParams. To free the space allocated for this structure, use AEndConversion . 
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ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 

17 AEOutOfMemory 

EXAMPLE 

For an example, see /usr/audio/examples/splayer .c 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASetupConversion ( ) was developed by HP. 

SEE ALSO 

AConvertBuffer(3X), AChooseSourceAttributes(3X), AChoosePlayAttributes(3X), 
AEndConversion(3X) 

Using the Audio Application Program Interface. 
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NAME 

ASimplePlayer - return gain matrix of basic play device 

SYNOPSIS 

#include <audio/Alib.h> 

AGainMatrix ASimplePlayer (Audio *audio); 

DESCRIPTION 

ASimplePlayer ( ) returns the gain matrix of the basic audio play device supported by the audio con- 
troller associated with the connection specified by audio . 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon succesfui completion, ASimplePlayer ( ) returns the gain matrix of the basic audio play device 
supported by the audio controller associated with the connection specified by audio . 

ERRORS 

ASimplePlayer ( ) does not return an error status. 

EXAMPLES 

The following example gets the gain matrix of the basic audio play device supported by the audio controller 
associated with the connection specified by audio. 

AGainMatrix *spmatrix; /* simple play gain matrix */ 
Audio *audio; /* audio connection */ 



/* get the simple record gain matrix */ 
spmatrix = ASimplePlayer (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASimplePlayer ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 
AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), 
ASetChannelGain(3X), ASetGain(3X), ASetSystemChannelGain(3X), ASimpleRecorder(3X). 

Using the Audio Application Program Interface. 
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NAME 

ASimpleRecorder - return gain matrix of basic recording device 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AGainMatrix ASimpleRecorder (Audio *audio); 

DESCRIPTION 

ASimpleRecorder ( ) returns the gain matrix of the basic audio recording device supported by the audio 
controller associated with the connection specified by audio. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon succesful completion, ASimpleRecorder ( ) returns the gain matrix of the basic audio recording 
device supported by the audio controller associated with the connection specified by audio . 

ERRORS 

ASimpleRecorder ( ) does not return an error status. 

EXAMPLES 

The following example gets the gain matrix of the basic audio recording device supported by the audio con- 
troller associated with the connection specified by audio . 

AGainMatrix *srmatrix; /* simple record gain matrix */ 
Audio *audio; /* audio connection */ 



/* get the simple record gain matrix */ 
srmatrix = ASimpleRecorder (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AS impleRecorder ( ) was developed by HP. 

SEE ALSO 

AGetChannelGain(3X) AGetGain(3X), AGetSystemChannelGain(3X), AGMGainRestricted(3X), 
AInputChannels(3X), AInputSources(3X), AMaxInputGain(3X), AMaxOutputGain(3X), 

AMinInputGain(3X), AMinOutputGain(3X), AOutputChannels(3X), AOutputDestinations(3X), 
ASetChannelGain(3X), ASetGain(3X), ASetSystemChannelGain(3X), ASimplePlayer(3X), 

Using the Audio Application Program Interface. 
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NAME 

asinh, acosh, atanh - inverse hyperbolic functions 

SYNOPSIS 

#include <math.h> 

double asinh (double x) ; 
double acosh (double x) ; 
double atanh (double x) ; 

DESCRIPTION 

aslnh(), acosh(), and atanh () return respectively the designated inverse hyberbolic sine, cosine, 
and tangent of their argument. 

When x is ±INFINITY , as inh ( ) returns iJNFINITY respectively. 

When x is +INFINITY , acosh ( ) returns +INFINITY. 

ERRORS 

/lib/Libm.a 

asinh(), acosh () , and atanh () return NaN and set errno to EDOM when x is NaN. In addi- 
tion, a message indicating DOMAIN error is printed on the standard error output. 

acosh ( ) also returns NaN and sets errno to EDOM if x < 1.0. 

atanh ( ) also returns NaN and sets errno to EDOM if Ire I > 1.0. 

These error-handling procedures can be changed with the function matherr ( ) (see matherr (3M)). 

/lib/libM.a 

No error messages are printed on the standard error output. 

aslnh(), acosh () , and at anh () return NaN and set errno to EDOM when x is NaN. 

acosh ( ) also returns NaN and sets errno to EDOM if x < 1.0. 

atanh ( ) also returns NaN and sets errno to EDOM if Ix I > 1.0. 

These error-handling procedures can be changed by using the _matherr ( ) function (see matherr(3M)). 
Note that _matherr ( ) is provided in order to assist in migrating programs from llbm. a to libM. a 
and is not a part of XPG3, ANSI C, or POSIX. 

DEPENDENCIES 
Series 300/400 

as lnh ( ) , acosh ( ) , and atanh ( ) are not supported on Series 300/400 systems. 

Series 700/800 

asinh ( ) , acosh ( ) , and atanh ( ) are not specified by any standard. They are provided in the PAl.l 
versions of the math library only. The +DA1 . 1 linker option (default on Series 700 systems) links in a 
PAl.l version automatically. A PAl.l library can also be linked in explicitly. For more information, see the 
HP-UX Floating-Point Guide. 

SEE ALSO 

exp(3M), matherr(3M). 
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NAME 

ASoundBitOrder - get bit order used for one-bit-per-sample data 

SYNOPSIS 

# include <audio/Alib.h> 

ABitOrder ASoundBitOrder (Audio *audio); 

DESCRIPTION 

ASoundBitOrder ( ) returns the bit order that will be used if data is one bit per sample. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, ASoundBitOrder ( ) returns the bit order that will be used if data is one bit 
per sample. 

ERRORS 

ASoundBitOrder ( ) does not return an error status. 

EXAMPLES 

The following example returns the bit order that will be used if the data is one bit per sample. 

ABitOrder bit_order; /* bit order */ 

Audio *audio; /* audio connection */ 



/* get bit order */ 

bit_order = ASoundBitOrder (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASoundBitOrder ( ) was developed by HP. 

SEE ALSO 

ASoundByteOrder(3X). 

Using the Audio Application Program Interface. 



HP-UX Release 9.0: August 1992 - 1 - 375 



ASoundByteOrder(3X) Series 700 Only ASoundByteOrder(3X) 



NAME 

ASoundByteOrder - get byte order of audio data accepted by audio controller for this connection 

SYNOPSIS 

ttinclude <audio/Alib.h> 

AByteOrder ASoundByteOrder (Audio *audio ) ; 

DESCRIPTION 

ASoundByteOrder ( ) returns the byte order of audio data accepted by the audio controller associated 
with the audio connection. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, ASoundByteOrder ( ) returns the byte order of audio data accepted by the 
audio controller associated with this connection. 

ERRORS 

ASoundByteOrder ( ) does not return an error status. 

EXAMPLES 

The following example returns the byte order accepted by the audio controller associated with the connec- 
tion specifie d by audio . 

AByteOrder byte_order; /* acceptable byte order */ 
Audio *audio; /* audio connection */ 



/* get acceptable byte order */ 
byte_order = ASoundByteOrder (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

ASoundByteOrder ( ) was developed by HP. 

SEE ALSO 

ASoundBitOrder(3X). 

Using the Audio Application Program Interface. 
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NAME m 

assert() - verify program assertion ■ 

SYNOPSIS 

#include <assert.h> 

int assert (int expression); 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is executed, if expression is false (zero), 
assert () prints: 

Assertion failed: expression, file xyz, line nnn 

on the standard error output and aborts. In the error message, xyz is the name of the source file and nnn 
the source line number of the assert ( ) statement. 

Compiling with the preprocessor option -DNDEBUG (see cpp(l)), or with the preprocessor control statement 
#def ine NDEBUG ahead of the #include <assert -h> statement, stops assertions from being com- 
piled into the program. 

WARNINGS 

The expression argument used by assert ( ) in compatibility mode cannot contain string literals or dou- 
ble quotes without escapes. 

SEE ALSO 

cpp(l), abort(3C). 

STANDARDS CONFORMANCE 

assert ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l, ANSI C 
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NAME 

AStopAudio - stop specified audio transaction 

SYNOPSIS 

#include <audio/Alib.h> 

void AStopAudio ( 

Audi o . * audi o , 

ATransID xid, 

AStopMode mode, 

ATransStatus *trans_status_return, 

long *status_return 
); 

DESCRIPTION 

AStopAudio ( ) stops the transaction specified in xid. A stopped transaction cannot be resumed. 

audio specifies the Audio structure associated with this connection. 

xid specifies the transaction ID that was returned by ACreateSBucket () or 

ALoadAFile(). 

mode specifies the stop mode: ASMLinkedTrans, ASMThisTrans, or ASMEndLoop. 

To stop the current and subsequent transactions in a linked list, use ASMLink- 
edTrans and specify the first transaction in the linked fist as xid. The current and 
subsequent transactions in the finked fist cannot be resumed after this stop. 

To stop only the current transaction in a finked list, use ASMThisTrans. The 
specified transaction stops immediately, even if it is in the middle of a loop, and the 
remaining transactions in the linked list continue immediately. 

To stop a looping transaction, use ASMEndLoop. The specified transaction stops at 
the end of the current loop. If the loop transaction is in a linked list, the remaining 
transactions continue. 

If xid is not in a finked list, ASMLinkedTrans ( ) has the same effect as ASMThis- 
Trans. 

trans _status_return receives the returned status value. Setting this argument to NULL prevents the data 
from being collected and returned, which may enhance performance. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return 

AENoError 

2 AEBadAudio 

3 AEBadValue 

15 AEBadTransactionID 

EXAMPLES 

The following example stops the transaction identified by xid, sets mode to stop the specified transaction, 
passes NULL for transjstat, and sets up status to receive an error status. 

Audio *audio; /* audio connection */ 

ATransID xid; /* transaction ID */ 

AStopMode smode; /* stop mode */ 

long status; /* error status */ 



/* stop transaction - xid returned from prior call */ 

smode = ASMThisTrans; 

AStopAudio (audio, xid, smode, NULL, fcstatus); 
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DEPENDENCIES ■ 

This function belongs to the Audio Library of functions that manage connections to an audio server. The I 

audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AStopAudio ( ) was developed by HP. 

SEE ALSO 

APauseAudio(3X), AResumeAudio(3X). 

Using the Audio Application Program Interface. 
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NAME 

AtAddCallback - add callback procedure for audio toolkit 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AtAddCallback ( 

Widget widget, 

char * event, 

XtCallbackProc proc, 

XtPointer client_data 
); 

DESCRIPTION 

AtAddCallback ( ) adds a callback for the audio toolkit to use. When the toolkit receives an event, it 
checks to see if a callback procedure has been entered for the event. If a procedure has been entered, the 
toolkit calls it. 

Note that a callback for AuNdataAva liable must be added for a record stream widget operation to 
work, and a callback for AuNdataNeeded must be added for a play stream widget operation to work. 

widget Name of the widget 

event Event type of the callback. Acceptable values are: 

AuNstarted AuNerror AuNdataNeeded 

AuNstopped AuNmonitor AuNloopStarted 

AuNpaused AuNpreempted AuNloopStopped 

AuNresumed AuNdataAva liable AuNbrokenConnection 
AuNcompleted 

Note: AuNBrokenConnection indicates that the connection to the server has been 
severed. A callback for this event should arrange for the application to exit gracefully. 

proc Name of the callback procedure. 

client_data Data that the client wants to use; can be NULL. 

ERRORS 

AtAddCallback ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface toolkit. The audio server must run on a 
system equipped with audio hardware. To find out whether or not your system has audio hardware, refer 
to the hardware manual provided with your system. 

AUTHOR 

At AddCal lback ( ) was developed by HP. 

SEE ALSO 

AtlnitializeO, AuCreatePlayO, AuCreateRecordO, AuInvokePlayO, AuInvokeRecord(). 

Using the Audio Application Program Interface. 
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NAME 

Atlnitialize - add audio event handler for this connection 

SYNOPSIS 

#include <audio/Alib.h> 

void Atlnitialize (Audio *a_connection) ; 

DESCRIPTION 

Atlnitialize ( ) adds the audio event handler for the specified server connection. The graphical toolkit 
must be initialized and AOpenAudioO must be called before calling Atlnitialize ( ) because 
AOpenAudioO returns the pointer to the Audio structure for the connection, and Atlnitialize () 
calls XtAddlnput ( ) . 

The audio toolkit cannot be used without the graphical toolkit. 

a_connection specifies the Audio structure associated with this connection. 

ERRORS 

Atlnitialize ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface toolkit. The audio server must run on a 
system that has audio hardware. To find out whether or not your system has audio hardware, refer to the 
hardware manual that accompanies your system. 

AUTHOR 

Atlnitialize () was developed by HP. 

SEE ALSO 

AtAddCallbackO, AtRemoveCallbackO, AuCreatePlayO, AuCreateRecord(), AuInvokePlayO, 
AtPlayWidgetO, AtRecordWidget(), AuInvokeRecord(). 

Using the Audio Application Program Interface. 



HP-UX Release 9.0: August 1992 - 1 - 381 



AtRemoveCallback(3X) Series 700 Only AtRemoveCallback(3X) 



NAME 

AtRemoveCallback - set callback to NULL 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AtRemoveCallback (Widget widget, char *event); 

DESCRIPTION 

AtRemoveCallback () sets to NULL a callback that was added by AtAddCallback( ) . The 
client_data field is also set to NULL. 

widget Name of the widget. 



it type of the callback. 


n.CCGpuS.ux6 VcuuSS 3X6* 




AuNstarted 


AuNerror 


AuNdataNeeded 


AuNstopped 


AuNmonitor 


AuNloopStarted 


AuNpaused 


AuNpreempted 


AuNloopStopped 


AuNresumed 


AuNda t aAva i 1 ab 1 e 


AuNbr okenConnec t i on 


AuNcompleted 







ERRORS 

AtRemoveCallback ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface toolkit. The audio server must run on a 
system equipped with audio hardware. To find out whether or not your system has audio hardware, refer 
to the hardware manual provided with your system. 

AUTHOR 

AtRemoveCallback ( ) was developed by HP. 

SEE ALSO 

Atlnitialize(), AuCreatePlayO, AuCreateRecordO, AuInvokePlayO, AuInvokeRecord(), AuPlayWidget(), 
AuRecordWidget(). 

Using the Audio Application Program Interface. 
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NAME 

AuCreatePlay - create an audio play widget 

SYNOPSIS 

ttinclude <audio/Play.h> 

extern Widget AuCreatePlay ( 
Widget parent, 
String *name, 
ArgList *arglist # 
irgcounu 



i«_jj..i _. 



uaiuiuaj 



); 



DESCRIPTION 

AuCreatePlay ( ) creates a play widget. 

If you use the streams facility, the toolkit creates a file descriptor in connectFd during Au Invoke PI ay ( ) . 
After calling AuInvokePlay ( ), retrieve the file descriptor by calling XtSetArg (args [0] , AuN- 
connectFd, &stream_fd) ; and then call XtGetValue (playWidget,args, 1) ;. Then, use the 
select ( ) , read ( ) , and write ( ) system calls. 

Call AStopAudio ( ) to stop the transaction. A callback routine for AuNStopped can close ( ) the 
file descriptor. 

Note that for a play streams operation to work, a callback routine for AuNdataNeeded must be added 
using At AddCal lback ( ) . 

To enable an application to use a widget after it is created, bind the widget library with the application as 
follows: 



Id myjile .o... 
Arguments 



■lAt -lAlib 



parent Name of the parent widget 

name Name for this widget 

arglist The argument list for the widget 

argcount The number of arguments in arglist. 

arglist can contain the following: 



gam 



fileFormat 



Volume, in percent of total gain. Acceptable values are from to 100. Default 
is system dependent. 

Audio file format. Acceptable values are: 



AuPAlaw 

AuPMulaw 

AuPLinear8 



AuPLinear80f f set 

AuFLinearl6 

AuPRiff 



AuFSun 
AuFUnknown 



dataFormat 



durationType 



duration 



fileName 



Default is AuFUnknown. 

Audio data format. Acceptable values are: 



AuDMulaw 
AuDAlaw 



AuDLinearl6 
AuDLinear8 



AuDLlnear80f f set 
AuDUnknown 



Default is AuDUnknown . 

Duration units. Acceptable values are: 

AuSamples AuFullLength 

Default is AuFullLength . 

Number of units to play. Acceptable values are 
~0 (-1, play until notified). 

Name of the file to play (must be set prior to invocation of the play widget). 
There is no default value. 



AuMilliseconds 



•1 to MAX INT. Default is 
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startTimeType 

startTime 

pause 
stop 

QUuiOKsOWlfiCilOTl 

streamOrFile 
SStream 

connectFd 

reserved 
speaker 

link 



loopCount 
priority 



channels 
samplingRate 



Type of start time unit. Acceptable values are AuSamples and AuMil- 
liseconds. Default is AuMilliseconds. 

Number of units into the file to begin recording. Acceptable values are to 
MAX_INT. Default value is (BOF). 

Start in paused state. Acceptable values are ON or OFF . Default is OFF. 

Stop mode. Acceptable values are: 



AuStopEndLoopTrans 
AuStopNone 



AuStopLinkTrans 
AuStopThisTrans 

Default is AuStopNone. 

Pointer to Audio structure for this connection, returned by AOpenAudio ( ) . 
Specifying a valid pointer for this argument is mandatory; the default value is 
NULL, which causes the program to fail. 

Source of audio data. Acceptable values are AuStreamor AuFile. Default is 
AuFile. 

Pointer to SStream structure for this AuStream-type widget. Specifying a 
valid pointer for this argument is mandatory; the default value is NULL, which 
causes the program to fail. 

File descriptor of the non -blocking connection made for the stream by the toolkit; 
created during AuInvokeRecord( ) . 



Speaker choice. Acceptable values are Aulnternal or AuExternal. 
Default is Aulnternal. 

name of another play widget; when link is finished playing, the current widget 
starts immediately and automatically. Default is NULL. 

The link feature enables two or more play widgets to be linked into a continuous 
play operation. Follow these steps to link two or more widets: 

1. Create widget A with pause ON and with NULL specified in link. 

2. Create widget B with pause ON and with A's name specified in link. 

3. Repeat step 2 for as many widgets as you want in the chain (creating 
C with B's name in link, and so on). 

4. Invoke widget A. 

Number of times to play this widget. Acceptable values are -1 to MAX_INT. 
Default is 0. Note that a value of -1 specifies an infinite loop. 

Priority level of play request. Acceptable values are: 

AuUrgent AuNormal AuHigh AuLow 

Default is AuNormal. 

Number of channels. Acceptable values are 1 or 2. Default is 1. 

Number of cycles per second. Most Series 700 systems support the following 
values: 

5512 11025 22050 44100 
8000 16000 32000 48000 

Default is 8000. 

To double-check the values that your system supports, use ASam- 
plingRates(). 

Values between 0.995 and 1.0125 times any of the supported values are handled 
at the supported rate. Rates outside these tolerances are converted by sound 
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bucket transactions to the nearest supported rate but cause streams transac- 
tions to fail and return AEBadSamplingRate. 

leftChannel Gain, in %. Acceptable values are 1 through 100. Default is system depen- 

dent. 

rightChannel Gain, in %. Acceptable values are 1 through 100. Default is system depen- 

dent. 

RETURN VALUE 

Upon successful completion, AuCreatePlay ( ) returns the widget ID. 

ERRORS 

AuCreatePlay ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface widget library. The audio server must 
run on a system that has audio hardware. To find out whether or not your system has audio hardware, 
refer to the hardware manual that accompanies your system. 

AUTHOR 

AuCreatePlay ( ) was developed by HP. 

SEE ALSO 

AtAddCallback(3X), AtInitialize(3X), AtRemoveCallback(3X), AuCreateRecord(3X), AuInvokePlay(3X), 
AuInvokeRecord(3X), AuPlayWidget(3X), AuRecordWidget(3X), AuSaveFile(3X). 

Using the Audio Application Program Interface. 
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NAME 

AuCreateRecord - create an audio record widget 

SYNOPSIS 

#include <audio/Record.h> 

extern Widget AuCreateRecord ( 

km -a~— 4- „ = _^_4- 

iuuvjci. ^aj.cut.f 

String *name, 
ArgList *arglist, 
Cardinal argcount 
); 

DESCRIPTION 

AuCreateRecord ( ) creates a record widget. 

If the record operation is file-based, the AuNdataAvailable event is returned when all of the data has 
been saved in the file. To use this information, add a callback routine for AuNdataAvailable using 
AtAddCallback(). 

If you use the streams facility, the toolkit creates a file descriptor in connectFd during Aulnvok- 
eRecord ( ) . After calling AuInvokeRecord ( ) , retrieve the file descriptor by calling 

XtSetArg(args [0] , AuNconnectFd, &stream_fd) ; 
and then call 

XtGetValue (recordWidget,args,l) ; . 

Then, use the select ( ) , read ( ) , and write ( ) system calls. 

After calling AStopAudio ( ) to stop the transaction, the application program must retrieve all the data 
in the buffer and close ( ) the file descriptor. A callback routine for AuNStopped can include all of 
these operations. 

Note that for a record streams operation to work, a callback routine for AuNdataAvailable must be 
added using At AddCal lback ( ) . 

To enable an application to use a widget after it is created, bind the widget library with the application as 
follows: 



Id my_file . o. 
Arguments 



■lAt -lAlib 



parent Name of the parent widget 

name Name for this widget 

arglist The argument list for the widget 

argcount The number of arguments in arglist. 

arglist can contain the following: 



gam 



fileFormat 



Volume, in per cent of total gain. Acceptable values are from through 100. 
Default is system-dependent. 

Audio file format. Acceptable values are: 



AuPMulaw 

AuPAlaw 

AuPLinearl6 



AuPSun 

AuFLinear8 

AuPRiff 



dataFormat 



Default is AuPUnknown. 

Audio data format. Acceptable values are: 



AuDMulaw 
AuDAlaw 



AuDLinearl6 
AuDLinear8 



AuFLinearSOffset 
AuFUnknown 



AuDLinear80f fset 
AuDUnknown 



Default is AuDUnknown . 



386 
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durationType 

duration 

fileName 

startTimeType 

startTime 

pause 
stop 

audioConnection 

streamOrFile 
SStream 

connectFd 

reserved 
writeMode 



Duration units. Acceptable values are: 

AuSamples AuMilliseconds AuFullLength 

Default is AuFullLength. 

Number of units to record. Acceptable values are -1 to MAX_INT. Default is 
~0 (-1, record until notified). 

Name of the file to receive the data (must be set prior to invocation of the record 
widget). There is no default value. 

Type of start time unit. Acceptable values are AuSamples and AuMil- 
liseconds. Default is AuMilliseconds. 

Number of units into the file to begin writing (when the recorded file is saved). 
Acceptable values are to MAX_INT . Default value is (BOF). 

Start in paused state. Acceptable values are ON or OFF . Default is OFF . 

Stop mode. Acceptable values are: 



AuStopEndLoopTrans 
AuStopNone 



AuStopLinkTrans 
AuStopThisTrans 

Default is AuStopNone. 

Pointer to Audio structure for this connection, returned by AOpenAUdio ( ) . 
Specifying a valid pointer for this argument is mandatory; the default value is 
NULL, which causes the program to fail. 

Source of audio data. Acceptable values are AuStreamor AuFile. Default is 
AuFile. 

Pointer to SStream structure for this AuStream-type widget. Specifying a 
valid pointer for this argument is mandatory; the default value is NULL, which 
causes the program to fail. 

File descriptor of the non-blocking connection made for the stream by the toolkit; 
created during AuInvokeRecord ( ) . 



channels 
samplingRate 



Mode for saving data. Acceptable values are: 

AuOverWrite Aulnsert 
AuTruncAppend 

Default is AuOverWrite. 

Number of channels. Acceptable values are 1 or 2 . Default is 1 . 

Number of cycles per second. Most Series 700 systems support the following values: 



5512 
8000 



11025 
16000 



22050 
32000 



44100 
48000 



leftChannel 

rightChannel 

audioln 



Default is 8000. 

To double check on the values that your system supports, use ASamplingRates ( ) . 

Values between 0.995 and 1.0125 times any of the supported values are handled at 
the supported rate. Rates outside these tolerances are converted by sound bucket 
transactions to the nearest supported rate, but cause streams transactions to fail and 
return AEBadSampl ingRat e. 

Gain, in %. Acceptable values are 1 through 100. Default is system-dependent. 

Gain, in %. Acceptable values are 1 through 100. Default is system-dependent. 

Line in or monaural microphone. Acceptable values are AuMicrophone or 
AuLineln. Default is AuMicrophone. 
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RETURN VALUE 

Upon successful completion, AuCreateRecord ( ) returns the widget ID. 

ERRORS 

AuCreateRecord ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface widget library. The audio server must 
run on a system that has audio hardware. To find out whether or not your system has audio hardware, 
refer to the hardware manual that accompanies your system. 

AUTHOR 

AuCreateRecord ( ) was developed by HP. 

SEE ALSO 

AtAddCallback(), Atlnitialize(), AtRemoveCallbackO, AuCreatePlayO, AuInvokePlayO, AuInvokeRecord() 
AuPlayWidget, AuRecordWidget, AuSaveFile(). 

Using the Audio Application Program Interface . 
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NAME 

AuInvokePlay - initiate a widget play operation 

SYNOPSIS 

#include <audio/Play.h> 

extern void AuInvokePlay (Widget widget); 

DESCRIPTION 

AuInvokePlay ( ) initiates a widget play operation. A play widget must be created before it can be 
invoked. If the application calls AuInvokePlay ( ) more than once, set up callbacks for AuNs topped 
and AuNcompieted. Use these notifications to avoid overlapping with a transaction that is still active 
from a prior AuInvokeP lay ( ) . 

widget the name of a play widget. 

ERRORS 

AuInvokePlay ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface widget library. The audio server must 
run on a system that has audio hardware. To find out whether or not your system has audio hardware, 
refer to the hardware manual that accompanies your system. 

AUTHOR 

AuInvokePlay ( ) was developed by HP. 

SEE ALSO 

AtAddCallback(), Atlnitialize(), AtRemoveCallback, AuCreatePlayO, AuCreateRecordO, AuInvokeRecordO, 
AuPlay Widget, AuRecordWidget, AuSaveFile(). 

Using the Audio Application Program Interface. 
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NAME 

AuInvokeRecord - initiate a widget record operation 

SYNOPSIS 

#lnclude <audio/Record.h> 

extern void AuInvokeRecord (Widget widget); 

DESCRIPTION 

AuInvokeRecord ( ) initiates a widget record operation. A record widget must be created before it can 
be invoked. If the application calls this function more than once, set up callbacks for AuNs topped and 
AuNcompleted. Use these notifications to avoid overlapping with a transaction that is still active from a 
prior AuInvokeRecord ( ) . 

widget the name of a record widget. 

ERRORS 

AuInvokeRecord ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface widget library. The audio server must 
run on a system that has audio hardware. To find out whether or not your system has audio hardware, 
refer to the hardware manual that accompanies your system. 

AUTHOR 

AuInvokeRecord ( ) was developed by HP. 

SEE ALSO 

AtAddCallbackO, Atlnitialize(), AtRemoveCallback(), AuCreatePlayO, AuCreateRecord(), AuInvokePlayO, 
AuPlayWidget, AuRecordWidget, AuSaveFile(). 

Using the Audio Application Program Interface. 
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NAME 

AUngrabServer - release server from exclusive use by this connection 

SYNOPSIS 

ttinclude <audio/Alib.h> 

void AUngrabServer (Audio *audio, long *status_return) ; 

DESCRIPTION 

AUngrabServer ( ) releases the server from exclusive use by this connection (exclusive use established 
by AGrabServer ( ) ). 

audio specifies the Audio structure associated with this connection. 

status jreturn receives the returned status of the operation unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status _return: 

AENoError 
2 AEBadAudio 

EXAMPLES 

The following example releases the server for general use and sets up status to receive an error status. 

Audio *audio; /* audio connection */ 
long status; /* error status */ 



/* release server for general use */ 
AUngrabServer (audio, fcstatus ) ; 



DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AUngrabServer ( ) was developed by HP. 

SEE ALSO 

AGrabServer(3X). 

Using the Audio Application Program Interface. 
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NAME 

AUpdateDataLength - update a file's header 

SYNOPSIS 

#include <audlo/Alib.h> 

void 
AUpdateDataLength ( 

Audio * audio, 

char * pathname, 

APilePormat filejormat, 

long * status jreturn ) ; 

DESCRIPTION 

AUpdateDataLength ( ) opens the file specified by pathname (if the specified filejormat requires data 
length or file length information in its header), determines the relevant lengths, writes them to the 
appropriate fields and closes the file. If the specified file format does not require a header with a data or file 
length field, AUpdateDataLength returns without doing anything. 

audio specifies the Audio structure associated with this connection. 

pathname the pathname of the audio file. 

filejormat the format of the audio file at pathname . 

status jreturn receives the returned status of the operation, unless it is set to NULL. 

ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

1 AESystemCall 

6 AEBadFileFormat 
17 AEOutOfMemory 
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EXAMPLE 

The following example updates header of the Sun/NeXT file at /myhome/a_dir/a_f lie . 

APilePormat file_fmt; /* file format */ 

Audio * audio; /* audio connection */ 

long status; /* status */ 



/* update file header of /myhome/a_dir/a_f lie with relevant lengths */ 

flle_fmt = AFPSun; 

char fname[] = /myhome/a_dir/a_f ile ; 

AUpdateDataLength( audio, fname, file_fmt / &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AUpdateDataLength( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 



HP-UX Release 9.0: August 1992 - 2 - 393 



AuPlayWidget(3X) 



Series 700 Only 



AuPlayWidget(3X) 



NAME 

AuPlayWidget - audio play widget 

SYNOPSIS 

#include <audio/Play .h> 

DESCRIPTION 

The audio play widget is a member of 
AuCreatePlay ( ) creates a play widget. 



.*&. *^UJLC Wll 



!cu ua»». 



If you use the streams facility, the toolkit creates a file descriptor in connectFd during AuInvokePlay ( ) . 
After calling AuInvokePlay ( ) , retrieve the file descriptor by calling 

XtSetArg (args [0] , AuNconnectFd, &stream_fd) ; 
then call 

XtGetValue (playWidget , args , 1 ) ; 

The select ( ) , read ( ) , and write ( ) system calls can then be used in the usual manner. 

Call AStopAudlo() to stop the transaction. A callback routine for AuNS topped may close the file 
descriptor. 

Note that for a play streams operation to work, a callback routine for AuNdataNeeded must be added 
using At AddCal lback ( ) . 

To enable an application to use a widget after it is created, bind the widget library with the application as 
follows: 



Id my_file . o., 

RESOURCES 

gain 

fileFormat 



dataFormat 

durationType 

duration 

fileName 

startTimeType 

startTime 

pause 
stop 



-lAt -lAllb 

Volume, in per cent of total gain. Acceptable values are from to 100. Default is 
system-dependent. 

Audio file format. Acceptable values are: 



AuPMulaw 
AuPAlaw 



AuFLinearl6 
AuPSun 



AuPLinear8 
AuPRlff 



AuPLinear80ff set 
AuPUnknown 



Default is AuPUnknown. 

Audio data format. Acceptable values are: 



AuDMulaw 
AuDAlaw 



AuDLlnearl6 
AuDLlnear8 



AuDLlnear80ff set 
AuDUnknown 



AuFullLength 



■1 to MAX_INT. Default is ~0 (-1, 



Default is AuDUnknown. 

Duration units. Acceptable values are: 

AuSamples AuMllliseconds 

Default is AuFullLength. 

Number of units to play. Acceptable values are 
play until notified). 

Name of the file to play (must be set prior to invocation of the play widget). There is 
no default value. 

Type of start time unit. Acceptable values are AuSamples and AuMll- 
liseconds. Default is AuMllliseconds. 

Number of units into the file to begin recording. Acceptable values are to 
MAX_INT. Default value is (BOF). 

Start in paused state. Acceptable values are ON or OFF. Default is OFF. 

Stop mode. Acceptable values are: 
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AuStopLinkTrans 
AuStopThisTrans 



AuStopEndLoopTrans 
AuStopNone 



audioConnection 

streamOrFile 
SStream 

connectFd 

reserved 
speaker 

link 



loopCount 
priority 



channels 
samplingRate 



leftChannel 
rightChannel 



Default is AuStopNone. 

Pointer to Audio structure for this connection, returned by AOpenAudio ( ) . Speci- 
fying a valid pointer for this argument is mandatory; the default value is NULL, which 
causes the program to fail. 

Source of audio data. Acceptable values are AuStream or AuFile. Default is 
AuPile. 

Pointer to SStream structure for this AuStream-type widget. Specifying a valid 
pointer for this argument is mandatory; the default value is NULL, which causes the 
program to fail. 

File descriptor of the non-blocking connection made for the stream by the toolkit; 
created during AuInvokeRecord ( ) . 

Speaker choice. Acceptable values are Aulnternal or AuExtemal. Default is 
Aulnternal. 

name of another play widget; when link is finished playing, the current widget starts 
immediately and automatically. Default is NULL. 

The link feature enables two or more play widgets to be linked into a continuous play 
operation. Follow these steps to link two or more widets: 

1. Create widget A with pause ON and with NULL specified in link. 

2. Create widget B with pause ON and with A's name specified in link . 

3. Repeat step 2 for as many widgets as you want in the chain (creating C 
with B's name in link, and so on). 

4. Invoke widget A. 

Number of times to play this widget. Acceptable values are -1 to MAX__INT. 
Default is . Note that a value of -1 specifies an infinite loop. 

Priority level of play request. Acceptable values are: 

AuUrgent AuNornial 
AuHigh AuLow 

Default is AuNormal. 

Number of channels. Acceptable values are 1 or 2 . Default is 1 . 

Number of cycles per second. The values that are supported by most Series 700 sys- 
tems are: 



5512 
8000 



11025 
16000 



22050 
32000 



44100 
48000 



Default is 8000. 

To double check on the values that your system supports, use AS amp 1 ingRat es ( ) . 
Values between 0.995 and 1.0125 times any of the supported values are handled at 
the supported rate. Rates outside these tolerances are converted by sound bucket 
transactions to the nearest supported rate, but cause streams transactions to fail and 
return AEBadSampl IngRat e. 

Gain, in percent. Acceptable values are 1 through 100. Default is system- 
dependent. 

Gain, in percent. Acceptable values are 1 through 100. Default is system- 
dependent. 
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DEPENDENCIES 

This widget belongs to the Audio Application Program Interface widget library. The audio server must run 
on a system that has audio hardware. To find out whether or not your system has audio hardware, refer to 
the hardware manual that accompanies your system. 

SEE ALSO 

AtAddCallback(). AtlnitializeO, AtRemoveCallbackQ, AuCreateEecordO, AuInvokePlayO, Aulnvok- 
eRecord(), AuRecordWidget, AuSaveFile(). 

Using the Audio Application Program Interface. 



396 - 3 - HP-UX Release 9.0: August 1992 



AuRecordWidget (3X) 



Series 700 Only 



AuRecordWidget ( 3X) 



NAME 

AuRecordWidget - audio record widget 

SYNOPSIS 

#include <audio/Record.h> 

DESCRIPTION 

The audio record widget is a member of the new Audio subclass of the X Core widget class. 

If the record operation is file-based, the AuNdataAvailable event is returned when all of the data has 
been saved in the file. To use this information, add a callback routine for AuNdataAvailable using 
AtAddCallback(). 

If you use the streams facility, the toolkit creates a file descriptor in connectFd during Aulnvok- 
eRecord ( ) . After calling AuInvokeRecord ( ) , retrieve the file descriptor by calling 

XtSetArg(args[0] , AuNconnectFd, &stream_fd) ; 
then call 

XtGetValue(recordWidget,args,l) ; . 

The select ( ) , read ( ) , and write ( ) system calls can then be used in the usual manner. 

After calling AStopAudio ( ) to stop the transaction, the application program must retrieve all the data 
in the buffer and close () the file descriptor. A callback routine for AuNStopped can include all of 
these operations. 

Note that for a record streams operation to work, a callback routine for AuNdataAvailable must be 
added using AtAddCallback ( ) . 

To enable an application to use a widget after it is created, bind the widget library with the application as 
follows: 

Idmyjile.o... -lAt -lAlib 



RESOURCES 

gain 

fileFormat 



dataFormat 

durationType 

duration 
fileName 
startTimeType 
startTime 



Volume, in percent of total gain. Acceptable values are from to 100. Default is 
system-dependent. 

Audio file format. Acceptable values are: 

AuFMulaw AuFLinearl6 AuFLinearS 
AuFAlaw AuFSun AuFRiff 

Default is AuFUnknown. 

Audio data format. Acceptable values are: 



AuFLinear80ff set 
AuFUnknown 



AuDMulaw 
AuDAlaw 



AuDLinearl6 
AuDLinearB 



AuDLinearSOff set 
AuDUnknown 



Default is AuDUnknown . 

Duration units. Acceptable values are: 

AuSamples AuMilliseconds AuFullLength 

Default is AuFullLength. 

Number of units to record. Acceptable values are -1 to MAX_INT . Default is ~0 (- 
1, record until notified). 

Name of the file to receive the data (must be set prior to invocation of the record 
widget). There is no default value. 

Type of start time unit. Acceptable values are AuSamples and AuMil- 
liseconds. Default is AuMilliseconds. 

Number of units into the file to begin writing (when the recorded file is saved). 
Acceptable values are to MAX_INT. Default value is (BOF). 
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pause 
stop 



audioConnection 

streamOrFile 
SStream 

connectFd 

reserved 
writeMode 



channels 
samplingRate 



leftChannel 

rightChannel 

audioln 



Start in paused state. Acceptable values are ON or OFF. Default is OFF. 
Stop mode. Acceptable values are: 



AuStopEndLoopTrans 
AuStopNone 



AuStopLinkTrans 
AuSt opThi sTrans 

Default is AuStopNone. 

Pointer to Audio structure for this connection, returned by AOpenAUdio ( ) . Speci- 
fying a valid pointer for this argument is mandatory. The default value is NULL, 
which causes the program to fail. 

Source of audio data. Acceptable values are AuStream or AuFile. Default is 
AuFile. 

Pointer to SStream structure for this AuStream-type widget. Specifying a valid 
pointer for this argument is mandatory. The default value is NULL, which causes the 
program to fail. 

File descriptor of the non-blocking connection made for the stream by the toolkit; 
created during AuInvokeRe cord ( ) . 



Mode for saving data. Acceptable values are: 

AuOverWrite AuTruncAppend Aulnsert 
Default is AUOverWrite . 

Number of channels. Acceptable values are 1 or 2. Default is 1. 
Number of cycles per second. Hardware-supported values are 



5512 
8000 



11025 
16000 



22050 
32000 



44100 
48000 



Default is 8000. 

Values between 0.995 and 1.0125 times any of the supported values are handled at 
the supported rate. Rates outside these tolerances are converted by sound bucket 
transactions to the nearest supported rate, but cause streams transactions to fail and 
return AEBadSampl IngRat e. 



Gain, in percent, 
dependent. 

Gain, in percent, 
dependent. 



Acceptable values are 
Acceptable values are 



through 100. Default is system- 
through 100. Default is system- 



Line in or mono microphone. Acceptable values are AuMicrophone or AuLlneln. 
Default is AuMicrophone. 

DEPENDENCIES 

This widget belongs to the Audio Application Program Interface widget library. The audio server must run 
on a system that has audio hardware. To find out whether or not your system has audio hardware, refer to 
the hardware manual that accompanies your system. 

SEE ALSO 

AtAddCallbackO, Atlnitialize(), AtRemoveCallback(), AuCreatePlayO, AuInvokePlayO, AuInvokeRecord(), 
AuPlayWidget, AuSaveFile(). 

Using the Audio Application Program Interface. 
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NAME 

AuSaveFile - save sound bucket data created by record widget 

SYNOPSIS 

#include <audio/Record.h> 

extern void AuSaveFile (Widget widget); 

DESCRIPTION 

AuSaveFile ( ) saves into a file the sound bucket data created by a record widget. 

After recording, prepare for the AuSaveFile (} call by calling XtSetArgO and XtSetValue () . 
For example: 

XtSetArg (args [ 0] , AuNf ileName, path_name) ; 
XtSetValue(recordWidget,args,l) ; 

widget The name of a record widget. 

ERRORS 

AuSaveFile ( ) does not return an error status. 

DEPENDENCIES 

This function belongs to the Audio Application Program Interface widget library. The audio server must 
run on a system that has audio hardware. To find out whether or not your system has audio hardware, 
refer to the hardware manual that accompanies your system. 

AUTHOR 

AuInvokePlay ( ) was developed by HP. 

SEE ALSO 

AtAddCallbackO, Atlnitialize(), AtRemoveCallback(), AuCreatePlayO, AuCreateRecord(), AuInvokePlayO, 
AuInvokeRecord(), AuPlayWidget(), AuRecordWidget(). 

Using the Audio Application Program Interface. 
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NAME 

AVendorRelease - get vendor release number of audio server for this connection 

SYNOPSIS 

ttlnclude <audio/Alib.h> 

int AVendorRelease (Audio *audio) ; 

DESCRIPTION 

AVendorRelease ( ) returns the vendor release number of the audio server for the connection specified 
by audio. 

audio specifies the Audio structure associated with this connection. 

RETURN VALUE 

Upon successful completion, AVendorRelease ( ) returns the vendor release number of the the audio 
server associated with this connection. 

ERRORS 

AVendorRelease ( ) does not return an error status. 

EXAMPLES 

The following example returns the vendor release number of the audio server for the connection specified by 
audio. 

int vendor_rel; /* vendor release number for server */ 
Audio *audio; /* audio connection */ 



/* get vendor release number for server */ 
vendor_rel = AVendorRelease (audio) ; 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AVendorRelease ( ) was developed by HP. 

SEE ALSO 

AProtocolRevision(3X), AProtocolVersion(3X), AServerVendor(3X). 

Using the Audio Application Program Interface. 
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NAME 

AWriteAFileHeader - write a header for an audio file 

SYNOPSIS 

# include <audio/Alib.h> 

long 
AWriteAFileHeader ( 

Audio 

char 

AP i 1 eFonaat 

Audi oAt tributes 

long 
); 



*audio , 
* pathname , 
filejbrmat , 
*audio_attributes , 
*status return 



DESCRIPTION 

AWriteAFileHeader ( ) opens the specified file (truncating it to zero if it exists, or creating it if it does 
not exist), and writes a file header suitable for the specified file format and attributes. 

audio specifies the Audio structure associated with this connection. 

pathname the pathname of the audio data file for which a header will be written. 

filejbrmat specifies format of the file for which the header will be written. Must be a valid 

format (not AFFUnknovm). 

audio jattributes specifies attributes of the audio file for which the header will be written. Must 
be a complete audio attributes structure. The header's data length will be writ- 
ten as zero if the duration field of audio jxttributes is set to ATTFu 11 Length . 

status jreturn receives the returned status of the operation, unless it is set to NULL. 

RETURN VALUE 

Upon successful completion, AWriteAFileHeader ( ) returns the length of the file header. 
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ERRORS 

If status jreturn is not set to NULL, one of the following is returned in status jreturn: 

AENoError 

1 AESystem Call 

6 AEBadFileFormat 
7_ AEBadDataFormat 
17 AUOutOFMemory 

EXAMPLE 

The following example writes a file header to the file /myhome/a_dir/a_f ile . au . 

APilePormat file_fmt; /* file format */ 
Audio * audio; /* audio connection */ 

long header_len; /* length of header */ 

AudioAttributes 

attribs; /* previously defined attributes */ 
long status; /* status */ 



/* write a Sun/NeXT file header to /myhome/a_dir/a_f ile */ 
char fname[] = /myhome/a_dir/ a_file.au ; 
file_fmt = APFSun; 

header_len = AWriteAPileHeader (audio, fname, file_fmt / 
fcattribs, &status); 

DEPENDENCIES 

This function belongs to the Audio Library of functions that manage connections to an audio server. The 
audio server must run on a system that has audio hardware. To find out whether or not your system has 
audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR 

AWriteAPileHeader ( ) was developed by HP. 

SEE ALSO 

Using the Audio Application Program Interface. 
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NAME 

jO, jl, jn, yO, yl, yn - Bessel functions 

SYNOPSIS 

#include <math.h> 

double jO (double x) ; 
double jl (double x) ; 
double jn(int n, double x) ; 
double yO (double x) ; 
double yl (double x) ; 
double yn(int n, double x) ; 

DESCRIPTION 

j ( ) and jl ( ) return Bessel functions of x of the first kind of orders and 1 respectively, jn ( ) 
returns the Bessel function of re of the first kind of order n. 

yO ( ) and yl ( ) return the Bessel functions of x of the second kind of orders and 1 respectively, yn ( ) 
returns the Bessel function of x of the second kind of order n. The value of a; must be positive. 

ERRORS 

/lib/libm.a 

Non-positive arguments cause y0(), yl(), and yn() to return the value -HUGE_VAL and to set 
errno to EDOM. They also cause a message indicating DOMAIN error to be printed on the standard error 
output. 

Arguments too large in magnitude cause j ( ) , j 1 ( ) , jn ( ) , yO ( ) , yl ( ) , and yn ( ) to return 0.0 and 
set errno to ERANGE. In addition, a message indicating TLOSS error is printed on the standard error out- 
put. 

j ( ) , j 1 ( ) , jn ( ) , yO ( ) , yl ( ) , and yn ( ) return NaN and set errno to EDOM when x is NaN or 
±INFINITY. In addition, a message indicating DOMAIN error is printed on the standard error output. 

These error-handling procedures can be changed with the function matherr(SM). 

/lib/libM.a 

No error messages are printed on the standard error output. 

Non-positive arguments cause yO ( ) , yl ( ) , and yn( ) to return the value NaN and to set errno to 
EDOM. 

Arguments too large in magnitude cause j0(), jl(), jn(),y0(),yl(), and yn ( ) to return 0.0 and 
set errno to ERANGE. 

j ( ) , j 1 ( ) , jn ( ) , yO ( ) , yl ( ) , and yn ( ) return NaN and set errno to EDOM when x is NaN or 
INFINITY. 

These error-handling procedures can be changed by using the _matherr ( ) function (see matherridM)). 
Note that _matherr ( ) is provided in order to assist in migrating programs from llbm.a to libM.a 
and is not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

isinf(3M), isnan(3M), matherr(3M). 

STANDARDS CONFORMANCE 



JO 

jo 

jl 
jl 

jn 
jn 

yo 
yo 



in libm.a: AES, SVID2, XPG2, XPG3 
in libM.a: AES, XPG3, XPG4 

in libm.a: AES, SVID2, XPG2, XPG3 
in libM.a: AES, XPG3, XPG4 

in libm.a: AES, SVID2, XPG2, XPG3 
in libM.a: AES, XPG3, XPG4 

in libm.a: AES, SVID2, XPG2, XPG3 
in libM.a: AES, XPG3, XPG4 
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yl ( ) in libm.a: AES, SVID2, XPG2, XPG3 
yl ( ) in libM.a: AES, XPG3, XPG4 

yn ( ) in libm.a: AES, SVID2, XPG2, XPG3 
yn ( ) in libM.a: AES, XPG3, XPG4 
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NAME 

bindresvport() - bind socket to privileged IP port 

SYNOPSIS 

ttinclude <sys/ types. h> 
#include <netinet/in.h> 

Int bindresvport (int sd, struct sockaddr_in *sin) ; 

DESCRIPTION 

bindresvport ( ) is used to bind a socket descriptor to a privileged IP port; that is, a port number in the 
range to 1023. sd is a socket descriptor that was previously denned by a successful call to socket(2). Upon 
successful completion of bindresvport ( ) , the sinjport field in the struct pointed to by sin contains the 
number of the privileged port bound to the sd socket. Due to the need to protect the port numbers used by 
various networking commands, bindresvport ( ) only returns a port number within a smaller subrange 
in the range of to 1023. 

Only the super-user can bind to a privileged port; this call fails for any other users. 

RETURN VALUE 

bindresvport ( ) returns if successful. Otherwise it returns -1 and sets errno to indicate the cause 
of the error. 

ERRORS 

bindresvport fails if any of the following conditions are encountered: 

[EPFNOSUPPORT] The value specified in the sinjamily field of the sockaddrjn struct was not 

AF_INET. 

[EBADF] sd is not a valid descriptor. 

[ENOTSOCK] sd is not a socket. 

[EADDRNOTAVAIL] The specified address is bad or not available from the local machine. 

[EADDRINUSE] The specified address is already in use. 

[EINVAL] The socket is already bound to an address, or the socket has been shut down. 

[EAFNOSUPPORT] Requested address does not match the address family of this socket. 

[EACCESS] The requested address is protected, and the current user has inadequate per- 

mission to access it. 

[EOPNOTSUPP] The socket whose descriptor is sd is of a type that does not support address 

binding. 

[ENOBUFS] Insufficient buffer memory is available. 

AUTHOR 

bindresvp ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

bind(2), socket(2). 
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NAME 

blopen(), blclose(), blread(), blget(), blset() - terminal block-mode library interface 

SYNOPSIS 

#include <sys/blmodeio.h> 

int blopen(int fildes); 

int blclose(int bfdes); 

int blread(int bfdes, char *buf # size_t nbyte) ; 

int blget(lnt bfdes, struct blmodeio *arg) ; 

int blset(int bfdes, const struct blmodeio *arg) ; 

DESCRIPTION 

This terminal library interface allows support of block-mode transfers with HP terminals. Block mode only 
affects input processing. Therefore, data is written with the standard write ( ) interface (see write(2)). 

In character mode, the terminal sends each character to the system as it is typed. However, in block mode, 
data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of 
data when the [Enter] key is pressed on the terminal. During block-mode data transmissions, the incom- 
ing data is not echoed by the interface and no special character processing is performed, other than recog- 
nizing a data block terminator character. For subsequent character mode transmissions, the existing ter- 
mio state (see termio(7)) continues to determine echo and character processing. 

Block-mode protocol has two component parts: block-mode handshake and block -mode transmission. 

Block-Mode Handshake 

At the beginning of a read, a trigger character is sent to the terminal to notify it that the system wants a 
block of data (the trigger character, if defined, is sent at the beginning of all reads, whether in character- or 
block-mode. It is necessary for block-mode reads to work correctly). 

After receiving the trigger character, and when the user has typed all the data into the terminal's memory 
and pressed the [Enter] key, the terminal sends an alert character to the system to notify it that the termi- 
nal has a block of data to send. 

The system might then send user-definable cursor-positioning or other data sequences to the terminal, such 
as for cursor-home or lock-keyboard. 

The system then sends a second trigger character to the terminal. In response, the terminal transmits the 
data block as described in the Block-Mode Transmission section. 

Block-Mode Transmission 

The second part of the block-mode protocol is the block-mode transmission. After the block-mode 
handshake has successfully completed, the terminal transmits the data block to the system. During this 
transmission of data, the incoming data is not echoed by the system and no special character processing is 
performed, other than recognizing the data block termination character. It is possible to bypass the block- 
mode handshake and have the block-mode transmission occur after only the first trigger character is sent, 
see CB_BMTRANS below. 

It is possible to intermix both character-mode and block-mode data transmissions. If CB_BMTRANS (see 
below) is set, all transfers are block-mode transfers. When is not set, character mode transmissions are pro- 
cessed as described in termio(7). In this case, if an alert character is received anywhere in the input data, 
the transmission mode is automatically switched to block mode for a single transmission. Any data 
received before the alert is discarded. The alert character can be escaped with a backslash (\) character. 

XON/XOFF Flow Control 

To prevent data loss, XON/XOFF flow control should be used between the system and the terminal. The 
IXOFF bit (see termio(7)) should be set and the terminal strapped appropriately. If flow control is not used, 
it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support 
XON/XOFF flow control.) 

Read Requests 

Read requests that receive data from block-mode transmissions do not return until the transmission is com- 
plete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data 
transmission error occurs, all subsequent data is discarded until the transmission is complete. The read 
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waits until a terminator character is seen, or until a time interval specified by the system has passed that is 
longer than necessary for the number of characters specified. 

The data-block-terminator character is included in the data returned to the user, and is included in the byte 
count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of 
bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are 
discarded. The user can determine if data was discarded by checking the last character of the returned 
data. If the last character is not the terminator character, then more data was received than was requested 
and data was discarded. 

The EIO error can be caused by several events, including errors in transmission, framing, parity, break, and 
overrun, or if the internal timer expires. The internal timer starts when the second trigger character is 
sent by the computer, and ends when the terminating character is received by the computer. The length of 
this timer is determined by the number of bytes requested in the read and the current baud rate, plus an 
additional ten seconds. 

User Control of Handshaking 

If desired, the application program can provide its own handshake mechanism in response to the alert char- 
acter by selecting the OWNTERM mode (see CB_OWNTERM below). With this mode selected, the driver 
completes a read request when the alert character is received. No data is discarded before the alert, and 
the alert is returned in the data read. The alert character may be escaped with a backslash (\) character. 
The second trigger is sent when the application issues the next read. 

blmode Control Calls 

First, the standard open ( ) call to a tty device must be made to obtain a file descriptor for the subsequent 
block-mode control calls (an open ( ) is done automatically by the system for stdin on the terminal). 

int bfdes; 

bfdes = blopen (int fildes) 

A call to blopen ( ) must be made before any block-mode access is allowed on the specified file 
descriptor, blopen ( ) initializes the block-mode parameters as described below. The return 
value from blopen ( ) is a block-mode file descriptor that must be passed to all subsequent 
block-mode control calls. 

Int blclose (int bfdes) 

A call to blclose ( ) must be issued before the standard close ( ) to ensure proper closure 
of the device (see close(2)). Otherwise unpredictable results can occur. The argument bfdes is 
the file descriptor returned from a previous blopen ( ) system call. 

int blread (int bfdes, char *buf, slze_t nbyte) 

The blread () routine has the same parameters as the read() sytem call (see read(2)). At 
the beginning of a read, the cb_trlglc character (if defined) is sent to the device. If 
CB_BMTRANS is not set, and no cb_alertc character is received, the read data is processed 
according to termio(l). If CB_BMTRANS is set, or if a non-escaped cb_alertc character is 
received, echo is turned off for the duration of the transfer, and no further special character pro- 
cessing is done other than that required for the termination character. The argument bfdes is 
the file descriptor returned from a previous blopen ( ) system call. 

int blget (Int bfdes, struct blmodelo *arg) 

A call to blget ( ) returns the current values of the blmodelo structure (see below). The 
argument bfdes is the file descriptor returned from a previous blopen ( ) system call. 

int blset (int bfdes, const struct blmodelo *arg) 

A call to blset ( ) sets the block-mode values from the structure whose address is org. The 
argument bfdes is the file descriptor returned from a previous blopen ( ) system call. 

blmode Structure 

The two block-mode control calls, blget () and blset (), use the following structure, defined in 
<sys/blmodeio.h>: 

ttdefine NBREPLY 64 

struct blmodelo { 

unsigned long cb_flags; /* Modes */ 

unsigned char cb_triglc; /* First trigger */ 
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unsigned char 
unsigned char 
unsigned char 
unsigned char 
char 



} 



cb_trig2c; 
cb_alertc; 
cb_termc; 
cb_replen; 
cb_reply[NBREPLY] ; 



/* Second trigger */ 

/* Alert character */ 

/* Terminating char */ 

/* cb_reply length */ 

/* optional reply */ 



The cb_f lags field controls the basic block-mode protocol: 



CB_BMTRANS 
CB OWNTERM 



0000001 
0000002 



Enable mandatory block-mode transmission. 
Enable user control of handshake. 



If CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode 
handshake is not required and data read is processed as block-mode transfer data. 



T\,p UlnrV 



handshake can still be invoked by receipt of an alert character as the first character seen. A blread ( ) 
issued with the CB_BMTRANS bit set causes any existing input buffer data to be flushed. 

If CB_BMTRANS is not set, and if the alert character is defined and is detected anywhere in the input 
stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the 
cb_trig2c character to the terminal, and a block-mode transfer follows. The alert character can be 
escaped by preceding it with a backslash (\). 

If CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped alert character. No input 
buffer flushing is performed, and the alert character is returned in the data read. This allows application 
code to perform its own block-mode handshaking. If the bit is clear, a non-escaped alert character causes 
normal block-mode handshaking to be used. 

The initial cb_f lags value is all-bits-cleared. 

There are several special characters (both input and output) that are used with block mode. These charac- 
ters and the initial values for these characters are described below. Any of these characters can be 
undefined by setting its value to 0377. 

cb_triglc (default DCl) is the initial trigger character sent to the terminal at the beginning of a read 
request. 

cb_trig2c (default DCl) is the secondary trigger character sent to the terminal after the alert charac- 
ter has been seen. 

cb_alertc (default DC2) is the alert character sent by the terminal in response to the first trigger char- 
acter. It signifies that the terminal is ready to send the data block. The alert character can 
be escaped by preceding it with a backslash ("\"). 

cb_termc (default RS) is sent by the terminal after the block-mode transfer has completed. It 
signifies the end of the data block to the computer. 

The cb_replen field specifies the length in bytes of the cb_reply field. If set to zero, the cb_reply 
string is not used. The cb_replen field is initially set to zero. 

The cb_reply array contains a string to be sent out after receipt of the alert character, but before the 
second trigger character is sent by the computer. Any character can be included in the reply string. The 
number of characters sent is specified by cb_replen. The initial value of all characters in the 
cb_reply array is NULL. 

RETURNS 

If an error occurs, all calls return a value of -1 and errno is set to indicate the error. If no error is 
detected, blread ( ) returns the number of characters read. All other calls return upon successful com- 
pletion. 

During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data 
in the user's buffer should be ignored as it is not complete. The following errors can be returned by the 
library calls indicated: 



blopenO 

[ENOTTY] 

blcloseQ 



The file descriptor specified is not related to a terminal device. 
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[ENOTTY] 

blread() 

[EDEADLK] 

[EFAULT] 



[EINTR] 

[EIO] 

[ENOTTY] 



blgetO 



blsetO 



[ENOTTY] 

[EINVAL] 
[ENOTTY] 



No previous blopen has been issued for the specified file descriptor. 

A resource deadlock would occur as a result of this operation (see lockf(2)). 

buf points outside the allocated address space. The reliable detection of this error is 
implementation dependent. 

A signal was caught during the read system call. 

An I/O error occured during block-mode data transmissions. 

No previous blopen has been issued for the specified file descriptor. 

No previous blopen has been issued for the specified file descriptor. 

An illegal value was specified in the structure passed to the system. 
No previous blopen has been issued for the specified file descriptor. 



WARNINGS 

Once blopen has been called with a file descriptor and returned successfully, that file descriptor should 
not subsequently be used as a parameter to the following system calls: close(), dup(), dup2(), 
fcntl ( ), ioctl ( ), read( ), or select ( ) until a blclose is called with the same file descriptor as 
its parameter. Additionally, scanf ( ) , f scanf ( ) , getc ( ) , getchar ( ) , f getc ( ) , and f getw ( ) 
should not be called for a stream associated with a file descriptor that has been used in a blopen ( ) call 
but has not been used in a blclose ( ) call. These functions call read ( ) , and calling these routines 
results in unpredictable behavior. 

AUTHOR 

blopen ( ) , blclose ( ) , blread( ) , blget ( ) , and blset ( ) were developed by HP. 

SEE ALSO 

termio(7). 
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NAME 

bsearch() - binary search a sorted table 

SYNOPSIS 

#include <stdllb.h> 

void *bsearch( 

const void *key, 

const void *base, 

size_t nel, 

size_t size, 

int (*compar) (const void *, const void *) 
); 

DESCRIPTION 

bsearch( ) is a binary search routine generalized from Knuth (6.2.1) Algorithm B. It returns a pointer 
into a table indicating where a datum may be found. The table must be previously sorted in increasing 
order according to a provided comparison function, key points to a datum instance to be sought in the table. 
base points to the element at the base of the table, nel is the number of elements in the table, size is the 
size of each element in the table, compar is the name of the comparison function, which is called with two 
arguments that point to the elements being compared. The function must return an integer less than, 
equal to, or greater than zero indicating that the first argument is to be considered less than, equal to, or 
greater than the second. 

NOTES 

The pointers to the key and the element at the base of the table should be of type pointer-to-element, and 
cast to type pointer-to-void. 

The comparison function need not compare every byte, so arbitrary data can be contained in the elements 
in addition to the values being compared. 

Although declared as type pointer-to-void, the value returned should be cast into type pointer-to-element. 

RETURN VALUE 

A NULL pointer is returned if the key cannot be found in the table. 

EXAMPLES 

The example below searches a table containing pointers to nodes consisting of a string and its length. The 
table is ordered alphabetically on the string in the node pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node and prints out the string and 
its length, or prints an error message. 

#include <stdio.h> 
#define TABSIZE 1000 



struct node { 

char * st ring; 

int length; 
}; 
struct node table [TABSIZE] ; 



/* these are stored in the table */ 



/* table to be searched */ 



struct node *node_ptr, node; 

int node_compare ( ); /* routine to compare 2 nodes */ 

char str_space[20] ; /* space to read string into */ 



node. st ring = str_space; 

while (scanf ("%s", node. string) != EOF) { 
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node_ptr = (struct node *)bsearch( (void *)(&node), 
(void *) table, tabsize, 
sizeof (struct node), node_compare) ; 
if (node_ptr != null) { 

(void) printf ("string = %20s, length = %d\n", 
node_ptr->string, node_ptr->length) ; 
} else { 

(void) printf ("not found: %s\n", node .string) ; 

} 
} 

} 

/* This routine compares two nodes based on an 

alphabetical ordering of the string field. */ 
int 

node_compare(nodel, node2) 
struct node *nodel, *node2; 
{ 

return strcmp(nodel->string, node2->string) ; 
} 

WARNINGS 

If the table being searched contains two or more entries that match the selection criteria, a random entry is 
returned by bsearch ( ) as determined by the search algorithm. 

SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 

STANDARDS CONFORMANCE 

bsearch ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

htonl(), htons(), ntohl(), ntohs() - convert values between host and network byte order 

SYNOPSIS 

# include <netinet/in.h> 

unsigned long htonl (unsigned long host long ) ; 
unsigned short htons (unsigned short hostshort); 
unsigned long ntohl (unsigned long net long ) ; 
unsigned short ntohs (unsigned short netshort); 

DESCRIPTION 

These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP- 
UX systems, network and host byte orders are identical, so these routines are defined as null macros in the 
include file <netinet/in.h>. 

These routines are most often used in conjunction with Internet addresses and ports as returned by 
gethostent ( ) and getservent ( ) (see gethostent(3N) and getservent(SNJ). Use these routines to 
write portable programs. 

AUTHOR 

byteorder ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

gethostent(3N), getservent(3N). 
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NAME 

cachectl() - flush and/or purge the cache 

SYNOPSIS 

#include <sys /cache. h> 

int cachectl (int cachecmd, void *address, size_t length); 

DESCRIPTION 

cachectl ( ) permits a program to flush or purge data in the data and/or instruction caches. The features 
provided by cachectl ( ) are not needed by most programs. It is primarily used for programs that do 
dynamic loading or contain self-modifying code. Programs that do dynamic loading or contain self- 
modifying code can use the CC_IPURGE request, after the new code has been written to memory, to 
ensure that the correct code will be fetched by the instruction cache during execution. The CC_FLUSH, 
CC_PUR6E, and CC_EXTPURGE requests should only be used by applications that are highly hardware 
dependent and which have detailed knowledge of hardware internals. 

The cachecmd parameter specifies what operations to carry out on the cache or chaches. cachecmd should 
contain one of the following values, which are defined in <sys /cache . h>: 

CC_PURGE Purge the cache. Dirty cache entries are discarded without being written to 

memory. A "dirty" cache entry is an entry that has been modified, but has not 
been written back to the corresponding memory location. 

CC_PLUSH Flush the cache. Dirty cache entries are copied back to the corresponding memory 

locations. This operation is the same as CC_PURGE on models that do not have a 
copyback cache. 

CC_I PURGE Flush any dirty data cache entries, then purge any instruction cache entries which 

are "stale". A "stale" instruction cache entry is an entry that is older than the 
corresponding memory location. This can happen if the corresponding memory 
location was written to (via the data cache). This operation is useful for self- 
modifying code. 

The following mask, defined in <sys /cache. h>, can be ORed together with one of the above values in 
order to purge the external cache (if one exists) at the same time. 

CC_EXTPURGE Purge the external cache (if any). 

The address parameter specifies the start address of the area to be flushed and/or purged. If the specified 
start address is a null pointer, the operation is applied to the entire cache or caches specified by the 
cachecmd parameter. Selective flushing and/or purging is not supported on all models. Some models have 
restrictions on the legal values for the address parameter. See DEPENDENCIES for details about specific 
hardware. 

The length parameter is used only when a start address is specified. It controls the length of the area to be 
flushed or purged. 

EXAMPLES 

The following call to cachectl ( ) requests that the entire data cache be flushed, followed by a purge of 
the instruction cache. 

cachectl (CC_IPURGE, 0, 0) ; 

RETURN VALUE 

cachectl () returns if the operation succeeds. Otherwise it returns -1. The semantics of 
cachectl (), when the address parameter contains a bad address, is subject to change and may vary 
from machine to machine. 

ERRORS 

cachectl ( ) fails and sets errno to the value indicated if: 

[EINVAL] cachecmd is not a a valid request. 

DEPENDENCIES 
Series 300/400 

The MC68020 and MC68030 processors do not have a copyback cache. Selective purging is not supported for 
the MC68020 and MC68030 processors. Selective purging and flushing is supported on the MC68040 processor, 
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but only under the following conditions: 

• If the length parameter is 16, the cache line which includes address is flushed and/or purged (i.e., 
the 4 least significant bits of the address are ignored). 

• If the length parameter is 4096, the page which includes address is flushed and/or purged (i.e., the 
12 least significant bits of the address are ignored). If the length parameter is not 16 or 4096, the 
operation is applied to the entire cache or caches specified by the cachecmd parameter. 

On the MC68040 microprocessor, CC_PURGE instead performs a CC_PLUSH if the length parameter 
is not 16 or 4096. 

AUTHOR 

cachectl ( ) was developed by HP. 
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NAME 

calendarO - return the MPE calendar date 

SYNOPSIS 

#include <portnls.h> 

unsigned short calendar (void) ; 

DESCRIPTION 

This routine returns the calendar date in the format: 

Bits 6 7 15 



Year of Century 


Day of Year 



RETURN VALUE 

An unsigned short integer containing the calendar format. 

WARNINGS 

This routine is provided for compatibility with MPE, another HP operating system. See portnls(5) for more 
information on the use of this routine. Use the Native Language Support routines for C programmers 
described on hpnls(5) for HP-UX NLS support. 

AUTHOR 

calendar ( ) was developed by HP. 

SEE ALSO 

portnls(5). 
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NAME 

catgetmsgO - get message from a message catalog 

SYNOPSIS 

#include <nl_types.h> 

char *catgetmsg( 

nl_catd catd, 

int set_num, 

int msg_num, 

char *buf, 

size_t buflen 
); 

DESCRIPTION 

catgetmsg ( ) reads message msg_num in set setjium from the message catalog mdentified by catd, a 
catalog descriptor returned from a previous call to catopen ( ) (see catopen(3C)). The return message is 
stored in buf, a buffer of length buflen bytes. 

A message longer than buflen - 1 bytes is silently truncated. The return message is always terminated with 
a null byte. 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If successful, catgetmsgO returns a pointer to the message in buf. Otherwise, catgetmsgO 
returns a pointer to an empty (null) string and sets errno to indicate the error. If buflen is greater than 
zero, the pointer returned is buf. 

ERRORS 

catgetmsg ( ) fails and errno is set to the value indicated if one of the following conditions is true: 

[EBADF] catd is not a valid catalog descriptor. 

[EINVAL] buflen is less than 1. 

[EINVAL] setjium is not in the message catalog. 

[EINVAL] The message catalog identified by catd is corrupted. 

[EINTR] A signal was caught during the read () system call. 

DEFAULT] buf points outside the allocated address space. The reliable detection of this error is 

implementation dependent. 

[ENOMSG] msgjium is not in the message catalog. 

DERANGE] A message longer than buflen- 1 bytes was truncated. 

AUTHOR 

catgetmsg ( ) was developed by HP. 

SEE ALSO 

catopen(3C), catgets(3C), read(2). 

STANDARDS CONFORMANCE 

catgetmsg ( ) : XPG2 
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NAME 

catgets() - get a program message 

SYNOPSIS 

#include <nl_types .h> 

char *catgets( 

nl_catd catd, 

int set_num, 

int msg_num, 

const char *dsf_str 
); 

DESCRIPTION 

cat get s ( ) reads message msgjium in set set_num from the message catalog identified by catd, a catalog 
descriptor returned from a previous call to catopen ( ) (see catopen(SC)). defjstr points to a default mes- 
sage string returned by catget s ( ) if the call fails. 

A message longer than NL_TEXTMAX bytes is truncated. The returned message string is always ter- 
minated with a null byte. NL_TEXTMAX is denned in <1 imi t s . h>. 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If the call is successful, catget s ( ) returns a pointer to an internal buffer area containing the null- 
terminated message string. If the call is unsuccessful, catget s ( ) returns a pointer to defjstr. 

ERRORS 

catget s ( ) fails and sets errno if the following condition is encountered: 

[EBADF] catd is not a valid catalog descriptor. 

[EINTR] A signal was caught during the read(2) system call. 

[EINVAL] The message catalog identified by catd is corrupted. 

[ENOMSG] Message identified by set_num or msgjnum is not in the message catalog. 

[ERANGE] A message longer than NL_TEXTMAX bytes was truncated. 

catgets ( ) fails and errno if any of the following conditions are encountered: 

WARNINGS 

catgets ( ) returns a pointer to a static area that is overwritten on each call. 

AUTHOR 

catgets ( ) was developed by HP. 

SEE ALSO 

catopen(3C), catgetmsg(3C). 

STANDARDS CONFORMANCE 

catgets ( ) : AES, XPG2, XPG3, XPG4 
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NAME 

catopen(), catclose() - open and close a message catalog for reading 

SYNOPSIS 

#include <nl_types.h> 

nl_catd catopen(const char *name, int of lag) ; 
int catclose(nl_catd catd) ; 

DESCRIPTION 

catopen ( ) opens a message catalog and returns a catalog descriptor, name specifies the name of the 
message catalog being opened. A name containing a slash (/) specifies a path name for the message cata- 
log. Otherwise, the environment variable NLSPATH is used (see environ(5)). If NLSPATH specifies more 
than one path, catopen ( ) returns the catalog descriptor for the first path on which it is able to success- 
fully open the specified message catalog. If NLSPATH does not exist in the environment, or if a message 
catalog cannot be opened for any NLSPATH-specified path, catopen ( ) uses a system-wide default path. 
The default is affected by the setting of LANG, name must not contain %N. 

A message catalog descriptor remains valid in a process until the process closes it, or until a successful call 
to one of the exec ( ) functions. A change in the setting of LANG category has no effect on existing open 
catalogs. 

If a file descriptor is used to implement message catalog descriptors, the PD_CLOEXEC flag will be set; see 
<fcntl.h>. 

oflag is reserved for future use and should be set to zero (0). The results of setting this field to any other 
value are undefined. 

catclose ( ) closes the message catalog catd, a message catalog descriptor returned from an earlier suc- 
cessful call to catopen ( ) . 

RETURN VALUE 

cat open () returns a message catalog descriptor if successful. Otherwise, a value of (nl_catd)-l is 
returned and errno is set to indicate the error. 

catclose ( ) returns if successful. Otherwise, -1 is returned and errno is set to indicate the error. 

ERRORS 

catopen ( ) fails, no message catalog is opened, and e r mo is set for the last path attempted if any of the 
following conditions is true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named catalog does not exist. 

[ENOENT] The path is null. 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] Read permission is denied for the named file. 

[EMFILE] The maximum number of file descriptors allowed are currently open. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENFILE] The system file table is full. 

[ENOTDIR] A component of the path prefix is not a directory. 

catclose ( ) fails if the following is true: 

[EBADF] catd is not a valid open message-catalog descriptor. 

WARNINGS 

When using NLSPATH, catopen () does not provide a default value for LANG. 

NOTES 

cat gets ( ) can be used to provide default messages when called following a failed catopen ( ) (see 
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catgets(SC)). catgets ( ) returns its def_str parameter if it is passed an invalid catalog descriptor. 

AUTHOR 

catopen ( ) was developed by HP. 

FILES 

/usr/ lib/nls Message catalog default path. 

SEE ALSO. 

catgets(3C), environ(5), <fcntl.h>, <nl_types.h>. 

STANDARDS CONFORMANCE 

catopen ( ) : AES, XPG2, XPG3, XPG4 

cat close ( ) : AES, XPG2, XPG3, XPG4 
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NAME 

catread( ) - MPE/RTE-style message catalog support 

SYNOPSIS 

ttinclude <portnls.h> 

int catread( 

int set_num # 

int msg_num / 

char *msg_buf, 

int buflen, 

/* arg, */ . . . 
\ . 

DESCRIPTION 

cat read ( ) reads message number msg_num of set setjium in the message catalog identified by fd, a file 
descriptor returned from a previous call to open ( ) (see open(2)). The return message is stored in buf, a 
buffer of length buflen bytes. 

The message read from the catalog can have embedded formatting information in the form ! [digit]. Excla- 
mation marks must be all numbered or all unnumbered. If exclamation marks are numbered, an exclama- 
tion mark followed by digit n is replaced by the nth. org. If exclamation marks are unnumbered, they are 
replaced by the orgs in serial order. If there are fewer args than exclamation marks, the results are 
undefined. If there are more args than exclamation marks, the excess args are ignored. 

A character in a message can be quoted (that is, made to stand for itself) by preceding it with a tilde (~). To 
use the special characters ! or ~ in a message, preceed the special character with ~. 

A message longer than buflen- 1 bytes is silently truncated. The return message is always terminated with 
a null byte. 

catread( ) is provided to support message catalog applications from The HP MPE and RTE operating sys- 
tems. 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If successful, cat read ( ) returns the length, in bytes, of the formatted message in msgjbuf. Otherwise, 
ifsetjium or msgjium is not found in the catalog, cat read ( ) returns a negative integer. 

ERRORS 

catreadO succeeds, but sets errno if the following condition is true: 

[ERANGE] Formatted message exceeds buflen -1 bytes. 

AUTHOR 

catread ( ) was developed by HP. 

SEE ALSO 

gencat(l), getmsg(3C), hpnls(5). 
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NAME 

cfgetospeed(), cfsetospeed(), cfgetispeed(), cfsetispeed() - tty baud rate functions 

SYNOPSIS 

ttinclude <termios.h> 

speed_t cfgetospeed( const struct termios *termios_p) ; 

Int cfsetospeed( struct termios *termios_p / speed_t speed); 

speed_t cf getispeed(const struct termios *termios_p) ; 

int cfsetispeed( struct termios *termios_p, speed_t speed); 

DESCRIPTION 

These functions set and get the input and output speed codes in the termios structure referenced by 
termios_p. The termios structure contains these speed codes representing input and output baud rates as 
well as other terminal related parameters. Setting the parameters on a terminal file does not become 
effective until tcsetattrO is successfully called. 

cf get o speed ( ) returns the output speed code from the termios structure referenced by 
termios j> . 

cf setospeed( ) sets the output speed code in the termios structure referenced by termios _p to 
speed. The speed code for a baud rate of zero, BO, is used to terminate the con- 
nection. If BO is specified, the modem control lines are no longer asserted, 
which normally disconnects the line. 

cf ge t i speed ( ) returns the input speed code from the termios structure referenced by termios_p . 

cf set i speed ( ) sets the input speed code in the termios structure referenced by termios_p to 
speed . 

RETURN VALUE 

cf getospeed ( ) returns the output speed code from the termios structure referenced by termios_p. 

cf get i speed ( ) returns the input speed code from the termios structure referenced by termios j). 

cf set i speed ( ) and cf setospeed( ) return zero upon successful completion. Otherwise, they return 
-1 and set errno to indicate the error. 

ERRORS 

cf set i speed ( ) and cf setospeed( ) fail when the following condition is encountered: 

[EINVAL] The value of speed is outside the range of possible speed codes as specified in 

<termios.h>. 

WARNINGS 

cf set i speed ( ) and cf setospeed( ) can be used to set speed codes in the termios structure that are 
not supported by the terminal hardware. 

SEE ALSO 

tcattribute(3C), termio(7). 

STANDARDS CONFORMANCE 

cf getispeed( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

cf getospeed ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
cf setispeed( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
cf setospeed( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

chownacl() - change owner and/or group represented in a file's access control list (ACL) 

SYNOPSIS 

#include <acllib.h> 

void chownacl ( 

Hnl- TuanfcrH o" 
— "— »»—»*>» i- -M- ^->-. i 

const struct acl_entry *acl, 
uid_t olduid, 
gid_t oldgid, 
uid_t newuid, 
gid_t newgid 
) ♦ 

Remarks: 

To ensure continued conformance with emerging industry standards, features described in this manual 
entry are likely to change in a future release. 

DESCRIPTION 

This routine alters an access control list (ACL) to reflect the change in a file's owner or group ID when an old 
file is copied to a new file and the ACL is also copied, chownacl ( ) transfers ownership (that is, it 
modifies base ACL entries) in a manner similar to chown ( ) (see chown(2)). The algorithm is described 
below and also in acl(5). 

The nentries parameter is the current number of ACL entries in the acl [ ] array (zero or more; a negative 
value is treated as zero). The olduid and oldgid values are the user and group IDs of the original file's 
owner, typically the st_uid and st_gid values from stat ( ) (see stat(2)). The newuid and newgid 
values are the user and group IDs of the new file's owner, typically the return values from geteuid ( ) 
and getegidO (see geteuid (2) and getegid(2)). 

If an ACL entry in acl [ ] has a uid of olduid and a gid of ACL_NSGROUP (that is, an owner base ACL 
entry), chownacl () changes uid to newuid (with exceptions - see below). If an entry has a uid of 
ACL_NSUSER and a gid of oldgid (that is, a group base ACL entry), chownacl ( ) changes gid to newgid. 
In either case, only the last matching ACL entry is altered; a valid ACL can have only one of each type. 

As with chown(2), if the new user or group already has an ACL entry (that is, a uid of newuid and a gid of 
ACL_NSGROUP, or a uid of ACL_NSUSER and a. gid of newgid), chownacl () does not change the old 
user or group base ACL entry; both the old and new ACL entries are preserved. 

As a special case, if olduid (oldgid) is equal to newuid (newgid), chownacl () does not search acl[] for 
an old user (group) base ACL entry to change. Calling it with both olduid equal to newuid and oldgid equal 
to newgid causes chownacl ( ) to do nothing. 

Suggested Use 

This routine is useful in a program that creates a new or replacement copy of a file whose original was (or 
possibly was) owned by a different user or group, and that copies the old file's ACL to the new file. Copying 
another user's and/or group's file is equivalent to having the original file's owner and/or group copy and 
then transfer a file to a new owner and/or group using chown ( ) . This routine is not needed for merely 
changing a file's ownership; chown ( ) modifies the ACL appropriately in that case. 

If a program also copies file miscellaneous mode bits from an old file to a new one, it must use chmod ( ) 
(see chmod(2)). However, since chmod ( ) deletes optional ACL entries, it must be called before 
setacl() (see setacl(2)). Furthermore, to avoid leaving a new file temporarily unprotected, the 
chmod ( ) call should set only the file miscellanous mode bits, with all access permission mode bits set to 
zero (that is, mask the mode with 07000). The cpacl ( ) library call encapsulates this operation, and han- 
dles remote files appropriately too. 

EXAMPLES 

The following code fragment gets stat ( ) information and the ACL from oldf lie, transfers ownership of 
newf lie to the caller, and sets the revised ACL to newf lie. 

#include <sys/types.h> 
#include <sys/stat.h> 
#include <sys/acl.h> 
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int nentries; 

struct acl_entry acl [NACLENTRIES] ; 

struct stat statbuf; 

if (stat ("oldfile", & statbuf) < 0) 
error (...); 

if ((nentries = getacl ("oldfile", NACLENTRIES, acl)) < 0) 
error (...); 

chownacl (nentries, acl, statbuf .st_uid, statbuf .st_gid, 
geteuid(), getegidO); 

if (setacl ("newfile", nentries, acl)) 
error (...); 

AUTHOR 

chownacl ( ) was developed by HP. 

SEE ALSO 

chown(2), getacl(2), getegid(2), geteuid(2), setacl(2), stat(2), acltostr(3C), cpacl(3C), setaclentry(3C), 
strtoacl(3C), acl(5). 
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NAME 

clearenv - clear the process environment 

SYNOPSIS 

#include <stdlib.h> 

int clearenv (void) ; 

DESCRIPTION 

clearenv ( ) clears the process environment. No environment variables are defined immediately after a 
call to clearenv ( ) . 

clearenv ( ) modifies the value of the pointer environ. This means that copies of that pointer are invalid 
after a call to clearenv ( ) . 

RETURN VALUE 

Upon successful completion, clearenv() returns zero; otherwise, it returns -1 and sets er mo to indi- 
cate the error. 

ERRORS 

clearenv ( ) fails if the following condition is encountered: 

[ENOMEM] Failed to free or reallocate memory for the process environment. 

SEE ALSO 

environ(5), getenv(3C), putenv(3C), <stdlib.h>. 

STANDARDS CONFORMANCE 

clearenv(): AES 
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NAME 

clock() - report CPU time used 

SYNOPSIS 

# include <time.h> 

clock_t clock(void); 

DESCRIPTION 

clock ( ) returns the amount of CPU time (in microseconds) used since the first call to clock ( ) . The 
time reported is the sum of the user and system times of the calling process and its terminated child 
processes for which it has executed wait ( ) or system ( ) (see wait(2) and system(3S)). To determine 
the time in seconds, the value returned by clock () should be divided by the value of the macro 
CLOCKS_PER_SEC. 

The resolution of the clock varies, depending on the hardware and on software configuration. 

If the processor time used is not available or its value cannot be represented, the function returns the value 
(clock_t)-l. 

WARNINGS 

The value returned by clock ( ) is defined in microseconds for compatibility with systems that have CPU 
clocks with much higher resolution. Because of this, the value returned wraps around after accumulating 
only 2147 seconds of CPU time (about 36 minutes). 

DEPENDENCIES 
Series 300/400 

The clock resolution is 20 milliseconds. 

Series 700/800 

The default clock resolution is 10 milliseconds. 

SEE ALSO 

times(2), wait(2), system(3S). 

STANDARDS CONFORMANCE 

clock ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 
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NAME 

clock( ) - return the MPE clock value 

SYNOPSIS 

#include <portnls.h> 

unsigned int clock(void); 

DESCRIPTION 

This routine returns the clock value in the MPE format. 

RETURN VALUE 

clock ( ) returns an unsigned int in the format: 

Bits 7 8 15 



Hour of Day 


Minute of Hour 



Bits 16 23 24 31 



Seconds 


Tenths of Seconds 



WARNINGS 

This routine is provided for compatibility with the HP MPE operating system. See portnls(5) for more infor- 
mation on the use of this routine. Use the Native Language Support routines for C programmers described 
in hpnls(5) for HP-UX NLS support. 

AUTHOR 

clock ( ) was developed by HP. 

SEE ALSO 

nlconvclock(3X), nlfmtclock(3X), portnls(5). 
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NAME 

confstrO - get string-valued configuration values 

SYNOPSIS 

#include <unistd.h> 

size_t confstr(int name, char *buf, size_t len) ; 

DESCRIPTION 

conf str ( ) provides a method for applications to get configuration-defined string values. Its use and pur- 
pose are similar to syaconf ( ) (see sysconf(2)) function, except that it is used where string values rather 
than numeric values are returned. 

The name parameter can take on the following name values, which are defined in <uni std . h>. 

_CS_PATH A default value for the PATH environment variable which can be used to locate com- 
mands in Section 1 of the HP-UX Reference and utilities defined in the POSIX.2 stan- 
dard that are currently implemented in the HP-UX operating system. 

If len is not zero, and if name is known and has a configuration-defined value, conf str ( ) copies that 
value into the len -byte buffer pointed to by buf. If the string to be returned is longer than len bytes, includ- 
ing the terminating null, conf str ( ) truncates the string to len - 1 bytes and null-terminates the result. 
The application can detect that the string was truncated by comparing the value returned by conf str ( ) 
with Zen. 

If Zen is zero and buf is NULL, conf str ( ) returns the integer value as defined below, but does not return 
a string. If len is zero but buf Is not NULL, the result is unspecified. 

RETURN VALUE 

If name is invalid, conf str () returns zero and sets errno to EINVAL. 

If name does not have a configuration-defined value, conf str ( ) returns 1 and returns a null string in 
buf. 

If name has a configuration-defined value, conf str ( ) returns the size of buffer that would be needed to 
hold the entire configuration-defined value. If this return value is less than len, the string returned in buf 
has been truncated. 

FILES 

/usr/include/unistd.h 

EXAMPLES 

The following code fragment calls confstrO to determine the correct buffer size for _CS_PATH, allo- 
cates space for this buffer, then gets the configuration value for _CS_PATH. 

#include <unistd.h> 
#include <stddef.h> 

size_t bufsize; 
char *buffer; 

buf size=conf str (_CS_PATH, NULL, (size_t)0) ; 
buffer=(char *)malloc (buf size) ; 
conf str (_CS_PATH, buffer, buf s ize) ; 

AUTHOR 

conf st r ( ) was developed by HP. 

SEE ALSO 

getconf(l), errno(2), sysconf(2), pathconf(2), fpathconf(2), malloc(3C). 

STANDARDS CONFORMANCE 

conf s t r ( ) : XPG4, POSLX.2 
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NAME 

toupperO, tolowerO, _toupper(), _tolower(), toascii() - translate characters 

SYNOPSIS 

ttinclude <ctype.h> 

int toupper(int c); 
int tolower(int c); 
int _toupper(int c); 
int _tolower(int c); 
int toascii (int c); 

DESCRIPTION 

toupper ( ) and tolower ( ) have as domain the range ofgetc(SS): the integers from -1 through 255. If 
the argument of toupperO represents a lowercase letter, the result is the corresponding uppercase 
letter. If the argument of tolowerO represents an uppercase letter, the result is the corresponding 
lowercase letter. All other arguments in the domain are returned unchanged. Arguments outside the 
domain cause undefined results. 

The macros _toupper() and _tolower() perform the same translations as toupperO and 
tolowerO, but have restricted domains and are faster. The domains of _toupper() and 
_tolower() are the integers from through 255. Arguments outside of the domain cause undefined 
results. 

toascii ( ) yields its argument with all bits turned off that are not part of a standard 7-bit ASCII charac- 
ter; it is intended for compatibility with other systems. 

WARNING 

toascii ( ) is supplied both as a library function and as a macro defined in the <ctype . h> header. Nor- 
mally, the macro version is used. To obtain the library function, either use a #undef to remove the macro 
definition or, if compiling in ANSI C mode, enclose the function name in parenthesis or take its address. 
The following examples use the library function for toasci i ( ) : 

#include <ctype.h> 
ftundef toascii 

main ( ) 
{ 

cl = toascii (c); 



#include <ctype.h> 

main ( ) 
{ 

int ( *conv_f unc ) ( ) ; 

cl = (toascii) (c) ; 

conv_func = toascii; 

} 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the translations to be done. 

International Code Set Support 

Single-byte character code sets are supported. 

428 - 1 - HP-UX Release 9.0: August 1992 



conv(3C) conv(3C) 



AUTHOR 

conv ( ) was developed by AT&T and HP. 

SEE ALSO 

ctype(3C), getc(3S), setlocale(3C), lang(5). _ 

STANDARDS CONFORMANCE I 

_tolower ( ) : AES, SVID2, XPG2, XPG3, XPG4 

_toupper ( ) : AES, SVID2, XPG2, XPG3, XPG4 

toascii ( ) : AES, 3VID2, XPG2, XPG3, XPG4 

tolower ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SIX.1, ANSI C 

toupper ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SIX.1, ANSI C 
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NAME 

cpacl(), fcpacl() - copy the access control list (ACL) and mode bits from one file to another 

SYNOPSIS 

#include <acllib.h> 

int cpacl( 

const char * fromfile, 

const char *tofile, 

mode_t frommode, 

uid_t fromuid, 

gid_t fromgid, 

uid_t touid, 

gid t togid 
); 

int f cpacl ( 

int fromfd, 

int tofd, 

mode_t frommode, 

uid_t fromuid, 

gid_t fromgid, 

uid_t touid, 

gid_t togid 
); 

Remarks: 

To ensure continued conformance with emerging industry standards, features described in this manual 
entry are likely to change in a future release. 

DESCRIPTION 

Both cpacl ( ) and f cpacl ( ) copy the access control list and mode bits (that is, file access permission 
bits and miscellaneous mode bits; see chmod(2)) from one file to another, and transfer ownership much like 
chown(2). cpacl ( ) and f cpacl ( ) take the following parameters: 

• Path names (fromfile and tofile) or open file descriptors (fromfd and tofd). 

• A mode value (frommode, typically the st_mode value returned by stat ( ) - see stat(2)) con- 
taining file miscellaneous mode bits which are always copied, and file access permission bits which 
are copied instead of the access control list if either file is remote. 

• User ID and group ID of the file (fromuid, touid and fromgid, togid) for transferring ownership. 
(Typically fromuid and fromgid are the st_uid and st_gid values returned by stat ( ) , and 
touid and togid are the return values from geteuid() and getegid() - see geteuid(2) and 
getegid(2).) 

When both files are local, the cpacl ( ) routines copy the access control list and call chovmacl ( ) (see 
chownacl (3C)) to transfer ownership from the fromfile to the tofile, if necessary. 

cpacl () (fcpaclO) handles remote copying (via NFS) after recognizing failures of getacl() 
(f getacl ( ) ) or setacl ( ) (f setacl ( ) ) (see setacl(2)). When copying the mode from fromfile (fromfd) 
to tofile (tofd), cpacl ( ) copies the entire frommode (that is, the file miscellaneous mode bits and the file 
access permission bits) to tofile (tofd) using chmod ( ) (f chmod( )). Some of the miscellaneous mode bits 
can be turned off; see chmod(2). 

cpacl ( ) (f cpacl) can copy an access control list from from file (fromfd) to tofile (tofd) without transfer- 
ring ownership, but ensuring error checking and handling of remote files. This is done by passing fromuid 
equal to touid and fromgid equal to togid (that is, four zeros). For remote files, fromuid, touid, fromgid, 
and togid are ignored. 

RETURN VALUE 

If successful, cpacl () and f cpacl ( ) return zero. If an error occurs, they set errno to indicate the 
cause of failure and return a negative value, as follows: 

—1 Unable to perform getacl ( ) (f getacl ( ) ) on a local fromfile (fromfd). 
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—2 Unable to perform chmod ( ) (f chmod ( ) ) on tofile (tofd) to set its file miscellaneous mode bits. 
cpacl() (fcpaclO) attempts this regardless of whether a file is local or remote, as long as 
fromfile (fromfd) is local. 

—3 Unable to perform setacl() (fsetacl()) on a local tofile (tofd). As a consequence, the file's 
optional ACL entries are deleted, its file access permission bits are zeroed, and its miscellaneous mode 
bits might be altered. 

—4 Unable to perform chmod () (fchmodO) on tofile (tofd) to set its mode. As a consequence, if 
fromfile (fromfd) is local, tofile's (tofd's) optional ACL entries are deleted, its access permission bits are 
zeroed, and its file miscellaneous mode bits might be altered, regardless of whether the file is local or 
remote. 

EXAMPLES 

The following code fragment gets stat information on oldf ile and copies its file miscellaneous bits and 
access control list to newf ile owned by the caller. If either file is remote, only the st_mode on old- 
file is copied. 

^include <sys/types.h> 
ttinclude <sys/stat.h> 

struct stat statbuf; 

if (stat ("oldf ile", & statbuf) < 
error (...); 

if (cpacl ("oldf ile", newf ile , statbuf . st_mode, 

statbuf .st_uid, statbuf .st_gid, geteuid(), getegidO) < 0) 



error (...); 



AUTHOR 

cpacl ( ) and f cpacl ( ) were developed by HP. 

SEE ALSO 

chown(2), getacl(2), getegid(2), geteuid(2), setacl(2), stat(2). acltostr(3C), chownacl(3C), setentry(3C), 
strtoacl(3C), acl(5). 
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NAME 

crtO.o, gcrtO.o, mcrtO.o, frtO.o, gfrtO.o, mfrtO.o - execution startup routines 

DESCRIPTION 

The C and Pascal compilers link in files crtO .o, gcrtO .o, or mcrtO .o to provide startup capabilities 
and environment for program execution. All are identical except that gcrtO.o and mcrtO .o provide 
additional functionality for gprof(l) and profiX) profiling support respectively. Similarly, the Fortran com- 
piler links in either f rtO . o, gf rt . o, or mf rt . o. 

The following symbols are defined in these routines: 

argc_value A variable of type int containing the number of arguments. 

argv_value An array of character pointers to the arguments themselves. 

_envlron An array of character pointers to the environment in which the program will 

run. This array is terminated by a null pointer. 

_SYSTEM_ID A variable of type int containing the system id value for an executable program. 

DEPENDENCIES 
Series 300/400 

The symbols above are shown as they are visible from C. To access them from assembly language, add an 
additional underscore to the beginning of the symbol. For example, an assembly language program refers 
to argc__value as argc_value. 

Series 300/400 startup files also define the following symbols which are listed as when used from assembly 
language. The state of these variables can be determined from C by using other library routines (see 
is_hw_present(3 C)). 

f lag_68010 A variable of type short. Non-zero if the processor is a 68010; zero if not. 

f loat_soft A variable of type short. Zero if the HP 98635 floating-point card is present; 

non-zero if it is not present. 

f loat_loc A constant defining the location in memory of the HP 98635 floating-point card. 

f lag_68881 A variable of type short. Non-zero if the HP68881 floating-point coprocessor is 

present; zero if it is not present. 

f lag_fpa A variable of type short. Non-zero if the HP 98248 floating-point card is 

present; zero if it is not present. 

f pa_loc A constant defining the location in memory of the HP 98248 floating-point card. 

Series 700/800 

All compilers on Series 700 and 800 use the crtO.o, gcrtO.o, or mcrtO.o file; the files frtO.o, 
gf rt . o, and mf rt . o do not exist. 

The Series 700 and 800 start-up files also define the following additional symbols: 

$START$ Execution start address. 

_start A secondary startup routine for C programs, called from $START$, which in 

turn calls main. This routine is contained in the C library rather than the 
crtO .o file. For Pascal and Fortran programs, this symbol labels the begin- 
ning of the outer block (main program) and is generated by the compilers. 

The initial address of the program's data pointer. The startup code loads this 
address into general register 27. 

The beginning of the stack unwind table. 

The end of the stack unwind table. 

$RECOVER_START The beginning of the try/recover table. 

$RECOVER_END The end of the try/recover table. 

The crtO . o file defines a null procedure for _mcount, so programs compiled with profiling can be linked 
without profiling. 



$global$ 

$UWWIND_START 
$UUWIND_END 
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The linker defines the following two symbols: 

text_start The beginning address of the program's text area. 

data_start The beginning address of the program's data area. 

AUTHOR 

The features described in this entry originated from AT&T UNIX System III. 

SEE ALSO 

cc(l), f77(l), ld(l), pc(l), profU), gprof(l), pc(l), profil(2), exec(2), is_hw_present(3C), monitor(3C). 
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NAME 

crypt, setkey, encrypt - generate hashing encryption 

SYNOPSIS 

ttinclude <unistd.h> 

char *crypt (const char *key, const char *salt); 

void setkey(const char *key) ; 

void encrypt (char block[64], int edf lag) ; 

DESCRIPTION 
crypt() : 

crypt ( ) is the password encryption function. It is based on a one way hashing encryption algorithm with 
variations intended (among other things) to frustrate use of hardware implementations of a key search. 

key is a user's typed password, salt is a two-character string chosen from the set [a-zA-ZO-9 . /] ; this 
string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is 
used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted pass- 
word. The first two characters are the salt itself. 

setkey () and encrypt (): 

The version of the encrypt ( ) function currently shipped on standard HP-UX systems fails when 
edf lag is non-zero (for decryption) and errno is set to ENOSYS in order to comply with industry stan- 
dards and U.S. government regulations. However, fully functional versions are available from HP in certain 
geographic areas, and behave as described below: 

setkey () and encrypt () provide (rather primitive) access to the actual hashing algorithm. The argu- 
ment to setkey ( ) is a character array of length 64 containing only the characters with numerical value 
and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56- 
bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or 
decrypt the string block with the function encrypt ( ) . 

The block argument to encrypt ( ) is a character array of length 64 containing only the characters with 
numerical value and 1. The argument array is modified in place to a similar array representing the bits 
of the argument after having been subjected to the hashing algorithm using the key that was set by set- 
key ( ) . If edflag is zero, the argument is encrypted; if non-zero it is decrypted. 

SEE ALSO 

crypt(l), login(l), passwd(l), getpass(3C), passwd(4). 

WARNINGS 

The return value points to static data whose content is overwritten by each call. 

STANDARDS CONFORMANCE 

crypt ( ) : SVID2, XPG2, XPG3, XPG4 

encrypt ( ) : SVID2, XPG2, XPG3, XPG4 
setkey ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

ctermid() - generate file name for terminal 

SYNOPSIS 

^include <stdio.h> 

char *ctermid(char *s); 

DESCRIPTION 

ctermid( ) generates a string that, when used as a pathname, refers to the the controlling terminal for 
the current process. 

If s is a NULL pointer, the string is stored in an internal static area, the contents of which are overwritten 
at the next call to ctermid ( ) , and the address of which is returned. Otherwise, s is assumed to point to a 
character array of at least L_ctermid elements; the path name is placed in this array and the value of s 
is returned. The constant L_ct ermid is defined in the <stdio.h> header file. 

If the process has no controlling terminal, the pathname for the controlling terminal cannot be determined, 
or some other error occurs, ctermid ( ) returns an empty string. 

NOTES 

The difference between ctermid () and ttyname() is that ttyname() must be handed a file 
descriptor and returns the actual name of the terminal associated with that file descriptor, while cter- 
mid ( ) returns a string (/dev/tty) that refers to the terminal if used as a file name, (see ttyname(3C)). 
Thus ttyname ( ) is useful only if the process already has at least one file open to a terminal. 

SEE ALSO 

ttyname(3C). 

STANDARDS CONFORMANCE 

ctermid ( ) : SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1 



I 
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NAME 

ctime(), localtimeO, gmtimeO, mktimeO, difltime(), asctime(), timezone(), daylight(), tzname(), tzset(), 
nl_ctime(), nl_cxtime(), nl_asctime(), nl_ascxtime() - convert date and time to string 

SYNOPSIS 

ttinclude <time.h> 



char *ctime (const time_t * timer) ; 

double difftime(time_t timel, time_t timeO); 

struct tm *gmtime (const time_t *timer) ; 

struct tm *localtime (const time_t *timer); 

time_t mktime (struct tm *timeptr); 

extern long time zone; 

extern int daylight; 

extern char *tzname[2]; 

void tzset (void) ; 

char *nl_asc time (const struct tm *timeptr, const char *format, int langid) ; 

char *nl_ascxtime (const struct tm *timeptr, const char *format); 

char *nl_c time (const time_t *timer, const char *format, int langid); 

char *nl_cxtime (const time_t *timer, const char *format); 



DESCRIPTION 

asctimeO 



ct ime ( ) 



gmtimeO 



localtimeO 



difftime() 
mktimeO 



Convert the broken-down time contained in the structure pointed to by timeptr and 
return a pointer to a 26-character string in the form: 

Sun Sep 16 01:03:52 1973\n\0 

All the fields have constant width. 

Convert the calendar time pointed to by timer, representing the time in seconds since 
the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: 

asctime (localt ime (timer) ) 

Convert directly to Coordinated Universal Time (UTC), the time standard used by the 
HP-UX operating system. gmtimeO returns a pointer to the tm structure described 
below. 

Correct for the time zone and any summer time zone adjustments (such as Daylight 
Savings Time in the USA), according to the contents of the TZ environment variable (see 
Environment Variables below). localtimeO returns a pointer to the tm structure 
described below. 

Return the difference in seconds between two calendar times: timel - timeO. 

Convert the broken-down time (expressed as local time) in the structure pointed to by 
timeptr into a calendar time value with the same encoding as that of the values 
returned by time{2). The original values of the tm_wday and tm vdav components 
of the structure are ignored, and the original values of the other components are not res- 
tricted to the ranges indicated below. 

A positive or zero value for tm_isdst causes mktime ( ) to initially presume that 
Daylight Saving Time respectively is or is not in effect for the specified time. A negative 
value for tm_isdst causes mktimeO to attempt to determine whether Daylight 
Saving Time is in effect for the specified time. 

Upon successful completion, all the components are set to represent the specified calen- 
dar time, but with their values forced to the ranges indicated below. The final value of 
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int 


tm_sec; 


/ 


int 


tm_min; 


/ 


int 


tm_hour; 


/ 


int 


tm_mday; 


/ 


int 


tm_mon ; 


/ 


int 


tm_year; 


/ 


int 


tm_wday; 


/ 


int 


tm_yday; 


/ 
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tm_mday is not set until tm_mon and tm_year are determined. mktime() 
returns the specified calendar time encoded as a value of type time_t. 

If the calendar time cannot be represented, the function returns the value (time_t) — 
1 and sets errno to ERANGE. Note the value (time_t) — 1 also corresponds to the 
time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time 
adjustments). Thus it is necessary to check both the return value and errno to reli- 
ably detect an error condition. 

tzset ( ) Sets the values of the external variables timezone, daylight, and tznarne according to 

the contents of the TZ environment variable (independent of any time value). The 
functions localtime ( ), mktimeO, ctime(), nl_ctime(), nl_cxtime(), 
asctime(), nl_asctime(), nl_ascxtime ( ) , and strftime() (see 
strftime(3C)) call tzset () and use the values returned in the external variables 
described below for their operations, t zset ( ) can also be called directly by the user. 

The <t ime . h> header file contains declarations of all relevant functions and externals. It also contains 
the tm structure, which includes the following members: 

seconds after the minute - [0,61] */ 
minutes after the hour - [0,59] */ 
hours - [0,23] */ 
day of month - [1,31] */ 
month of year - [0,11] */ 
years since 19 00 */ 
days s ince Sunday - [0,6] * / 
days since January 1 - [0,365] */ 
int tm_isdst; /* daylight savings time flag */ 

The value of tm_isdst is positive if a summer time zone adjustment such as Daylight Savings 
Time is in effect, zero if not in effect, and negative if the information is not available. 

The external variable timezone contains the difference, in seconds, between UTC and local standard time 
(for example, in the U.S. Eastern time zone (EST), timezone is 5*60*60). The external variable day- 
light is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The 
external variable t zname [ 2 ] contains the local standard and local summer time zone abbreviations as 
specified by the TZ environment variable. 

EXTERNAL INFLUENCES 
Locale 

The LC_TIME category determines for the functions nl_cxt ime ( ) , nl_ct ime ( ) , nl_ascxt ime ( ) , 
and nl_asctime ( ) the characters to be substituted for the directives described in strftime(3C) as being 
from the locale. It also determines the default output format used when a null format string is supplied to 
these functions. 

The LC_CTYPE category determines the interpretation of the bytes within format as single and/or multi- 
byte characters. 

Environment Variables 

The tzset ( ) function uses the contents of TZ to set the values of the external variables timezone, 
daylight , and tznarne. TZ also determines the time zone name substituted for the %Z and %z 
directives and the time zone adjustments performed by localtime(), mktime(), ctime(), 
nl__ctime ( ) , and nl_cxtime ( ) . Two methods for specifying a time zone within TZ are described in 
environ(5). 

International Code Set Support 

' l i Single- and multi-byte character code sets are supported. 

WARNINGS 

Return values point to static data whose contents is overwritten by each call. 

The range of tm_sec ( [0, 61] ) extends to 61 to allow for the occasional one or two leap seconds. How- 
ever, the "seconds since the Epoch" value returned by time(2) and passed as the timer argument does not 
include accumulated leap seconds. The tm structure generated by localtime () and gmtime() will 
never reflect any leap seconds. Upon successful completion, mkt ime ( ) forces the value of the tm_sec 
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component to the range [0,59]. 

ct ime ( ) , nl_cxtime ( ) , nl_ctime ( ) , asctime ( ) , nl_ascxtime ( ) , and nl_asctime ( ) are 
considered obsolescent and may be removed in a future release. Use of strftime(3C) is recommended in 
their stead. 

AUTHOR 

ct iros ( ) was developed by AT&T and HP. 

SEE ALSO 

time(2), nl_init(3C), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), lan- 
ginfo(5). 

STANDARDS CONFORMANCE 

ct ime ( ) : AES, SVTD2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.I, ANSI C 
asctime ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

daylight: AES, SVID2, XPG2, XPG3, XPG4 
dif f time ( ) : AES, XPG4, ANSI C 

gmtime ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.I, ANSI C 
localt ime ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

mktime ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.I, ANSI C 
nl_ascxtime ( ) : XPG2 

nl_cxtime():XPG2 

time zone: AES, XPG2, XPG3, XPG4 

tzname: AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
tzset ( ) : AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.I 
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NAME 

isalpha(), isupper(), islower(), isdigit(), isxdigit(), isalnum(), isspace(), ispunct(), isprint(), isgraph(), 
iscntrK), isasciiO - classify characters 

SYNOPSIS 

#include <ctype.h> 

int isalnum(int c) ; 

int isalpha(int c); 

int iscntrl(int c); 

int isdigit(int c) ; 

int isgraph(int c) ; 

int islower(int c) ; 

int isprint(int c); 

int ispunct(int c); 

int isspace(int c) ; 

int isupper(int c) ; 

int isxdigit (int c); 

int isascii(int c) ; 

DESCRIPTION 

These functions classify character-coded integer values according to the rules of the coded character set 
identified by the last successful call to setlocale( ) (see setlocale(SC)). Each function is a predicate 
returning non-zero for true, zero for false. 

If set locale ( ) has not been called successfully, characters are classified according to the rules of the 
default ASCII 7-bit coded character set (see setlocale(SC)). 

isasciiO is defined on all integer values; the other functions are defined for the range -1 (EOF) 
through 255. 

The functions return non-zero under the following circumstances; zero otherwise: 

isalpha(c) c is a letter. 

isupper (c) c is an uppercase letter. 

i s 1 owe r ( c ) c is a lowercase letter. 

isdigi t ( c) c is a decimal digit (in ASCII: characters [0-9]). 

isxdigit(c) cisa hexadecimal digit (in ASCII: characters [0-9], [A-F] or [a-f]). 

isalnum ( c) c is an alphanumeric (letters or digits). 

is space (c) c is a character that creates "white space" in displayed text (in ASCII: space, tab, 

carriage return, new-line, vertical tab, and form-feed). 

ispunct (c) c is a punctuation character (in ASCII: any printing character except the space 

character (040), digits, letters). 

i spr int ( c ) c is a printing character. 

isgraph(c) cis a visible character (in ASCII: printing characters, excluding the space character 

(040)). 

iscntrl (c) c is a control character (in ASCII: character codes less than 040 and the delete 

character (0177)). 

isascii (c) c is any ASCII character code between and 0177, inclusive. 

If the argument to any of these functions is outside the domain of the function, the result is undefined. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the classification of character type. 

International Code Set Support 

Single-byte character code sets are supported. 
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WARNINGS 

These functions are supplied both as library functions and as macros denned in the <ctype .h> header. 
Normally, the macro versions are used. To obtain the library function, either use a #unde£ to remove the 
macro definition or, if compiling in ANSI-C mode, enclose the function name in parenthesis or take its 
address. The following example uses the library functions for isalphaO, isdigit(), and 
isspace(): 

#include <ctype.h> 
#undef isalpha 

main() 
{ 

int (*ctype_func) ( ) ; 

if ( isalpha (c) ) 

if ( (isdlgit) (c) ) 

ctype_func = isspace; 



AUTHOR 

ctype ( ) was developed by AT&T and HP. 

SEE ALSO 

setlocale(3C), ascii(5). 

STANDARDS CONFORMANCE 



isalnumO 
isalpha () 

isascii( ) 
iscntrl( ) 

isdigitO 
isgraphO 

is lower ( ) 
isprint () 

ispunct ( ) 
isspace () 

isupperO 



AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

AES, SVID2, XPG2, XPG3, XPG4 

AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 



isxdigit ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
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NAME 

cursesO - CRT screen handling and optimization package 

SYNOPSIS 

# include <curses.h> 

cc [flags ] file ... -lcurses [libraries ] 

DESCRIPTION 

These routines provide a method for updating screens with reasonable optimization. To initialize curses 
routines, initscrO must be called before calling any other routine that deals with windows and 
screens, endwin ( ) should be called before exiting. To get character-at-a-time input without echoing, 
(most interactive, screen oriented-programs need this) after calling initscr ( ) the program should call: 

nonl ( ) ; cbreak ( ) ; noecho ( ) ; 

The full curses interface permits manipulation of data structures called "windows", which can be 
thought of as two-dimensional arrays of characters representing all or part of a CRT screen. A default win- 
dow called stdscr is supplied, and others can be created using newwin. Windows are referred to by 
variables declared WINDOW *, the type WINDOW is defined in <curses.h> to be a C structure. These 
data structures are manipulated by using functions described below, among which the most basic are 
move ( ) , and addch ( ) . (More general versions of these functions are included. Their names begin with 
w, allowing the programmer to specify a window. Routines not beginning with w affect stdscr.) Then 
ref resh ( ) is called, telling the routines to make the user's CRT screen resemble stdscr. 

Mini-Curses is a subset of curses which does not allow manipulation of more than one window. To invoke 
this subset, use -DMINICURSES as an option to the cc(l) command. This level is smaller and faster than 
full curses. 

If the environment variable TERMINPO is denned, any program using curses checks for a local terminal 
definition before checking in the standard place. For example, if the standard place is 
/usr/lib/terminfo, and TERM is set to vtlOO, the compiled file is normally found in 
/usr/lib/terminf o/v/vtlOO (the v is copied from the first letter of vtlOO to avoid creation of 
huge directories). However, if TERMINPO is set to /usr/mark/myterms, curses first checks 
/usr/mark/myterms/v/vtlOO, then, if that fails, checks /usr/lib/terminf o/v/vtlOO. This 
is useful for developing experimental definitions, or when write permission in /usr/lib/terminfo is 
not available. 

Functions 

All routines listed here can be called when using the full curses. Those marked with an asterisk can be 
called when using Mini-Curses. 

addch (ch ) * Add a character to stdscr (similar to putchar ( ) ; wraps to next line 

at end of line). 

addstr(stfr)* Call addch () with each character in str 

at t r of f ( attrs ) * Turn off attributes named 

at t r on (attrs ) * Turn on attributes named 

attrset (attrs ) * Set current attributes to attrs 

baudrate ( ) * Current terminal speed 

beep () * Sound beep on terminal 

box (win, vert, hor) Draw a box around edges of win. vert and hor are chars to use for 

vertical and horizontal edges of box 

clear () Clear stdscr 

c 1 earok ( win , bf) Clear screen before next redraw of win 

c 1 rt obot ( ) Clear to bottom of stdscr 

c 1 r t oe o 1 ( ) Clear to end of fine on stdscr 

cbreak ( ) * Set cbreak mode 

delay_output (ms ) * Insert ms millisecond pause in output 

de lch ( ) Delete a character 

de let e In ( ) Delete a line 

de lwin ( win ) Delete win 

doupdateO Update screen from all wnooutrefresh() 

echo ( ) * Set echo mode 
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endwin ( ) * 

erase () 

erasechar( ) 

f ixterm( ) 

flashO 

flushinpO* 

getch() 

getstr {str) 

gettmode ( ) 

getyx{win, y, x) 

has_ic ( ) 

has_il() 

idiokiuw, 6/")* 

inch() 

initscrO* 

insch(c) 

insertln() 

intrf lush {win, bf) 

keypad (wire, bf) 

killcharO 

leaveokfwm, flag) 

longname ( ) 
meta {win , flag ) * 
move {y , x)* 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 



End window modes 

Erase stdscr 

Return user's erase character 

Restore tty to "in-curses" state 

Flash screen or beep 

Throw away any type-ahead characters 

Get a char from tty 

Get a string through stdscr 

Establish current tty modes 

Get (y, x) co-ordinates 

True if terminal can do insert character 

True if terminal can do insert line 

Use terminal's insert/delete line if bf\= 

Get char at current (y, x) co-ordinates 

Initialize screens 

Insert a char 

Insert a line 

Interrupts flush output if bf is TRUE 

Enable keypad input 

Return current user's kill character 

Permissible to leave cursor anywhere after refresh if flag !=0 for win; 

otherwise cursor must be left at current position. 

Return verbose name of terminal 

Allow meta characters on input if flag != 

move to (y, x) on stdscr 

move {y , x ) then addch {ch ) 

Similar... 



mvcur {oldrow, oldcol, newrow, newcol) 

Low-level cursor motion 



Similar to delch ( ) , but move {y , x ) first 
etc. 



mvdelch(y, x) 

mvgetchCy, x) 

mvgetstrCy, x) 

mvinch {y , x ) 

mvinsch(y, x, c) 

mvpr intw {y , x , fmt , args ) 

mvscanw(y, x, fmt, args) 

mvwaddch(«>i», y , x, ch) 

mvwaddstr {win, y, x, str) 

mvwdelch(u>«i, y,,x) 

mvwgetch(u>wi, y,, x) 

mvwgetstr {win, y ,, x) 

mvwin(«;m, by,, bx) 

mvwinch {win, y,,x) 

mvwinsch(«;ire, y, x, c) 

mvwprintw(«;m, y , x, fmt, args) 

mvwscanw(«;m, y, x, fmt, args) 

newpad {nlines , ncols ) Create a new pad with given dimensions 

newt erm( type, outfd, infd) Set up new terminal of given type to output on outfd, using input (if 

needed) from infd 
newwin {lines, cols, begin jy , begin jn) 

Create a new window 
nl ( ) * Set new-line mapping 

nocbreakO* Unset cbreak mode 

node lay {win , bf) Enable nodelay input mode through getch ( ) 

noecho ( ) * Unset echo mode 

nonl ( ) * Unset new-line mapping 

no raw ( ) * Unset raw mode 

over lay ( winl , win2 ) Overlay winl on win2 
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overwrite (winl , win2 ) Overwrite winl on win2 

pnoutref resh(porf, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

Similar to prefreshO but with no output until doupdate ( ) 

called 
pref resh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

Refresh from pad starting with given upper left corner of pad with 



printw(/m£, argl, arg2, ... ) 

raw ( ) * 

refresh. ( ) * 

resettermO* 

resettyO* 

savetermO* 

savettyO* 

scanw(/m<, argl, arg2, ... ) 

scroll (win) 

Bcrollok. (win, flag) 

set_term (new ) 

setscrreg(£, 6) 



output to given portion of screen 

printf ( ) on stdscr 

Set raw mode 

Make current screen look like stdscr 

Set tty modes to "out of curses" state 

Reset tty flags to stored value 

Save current modes as "in curses" state 

Store current tty flags 

scanf ( ) through stdscr 

Scroll win one line 

Allow terminal to scroll if flag != 

Switch to terminal new 

set user scrolling region to lines t through b 

Establish terminal with given type 



sett erm (type) 

setupterm (for/re, filenum, errret) 

standend ( ) * Clear standout mode attribute 

standout ( ) * Set standout mode attribute 

subwin(u>ire, lines, cols, begin _y , begin _x) 

create a subwindow 



touchwin (win ) 

traceoff () 

traceonO 

typeahead (fd ) 

unctrl (ch)* 

waddch(u>ire, ch) 

waddstr(«>ire, str) 

watt rof f (win , attrs ) 

wattron(u>m, attrs) 

watt rset (win , attrs ) 

wclear (win) 

wclrtobot (win) 

wclrtoeol (win) 

wdelch(wre're, c) 

wdeleteln(w;ire) 

werase(w;ire) 

vrgetch (win) 

wgetstr (win , str) 

winch (wire) 

winsch(Hrere, c) 

wins ert In (win) 

wmove(u>m, y, x) 

wnout refresh (win ) 

wprintw(w;w, fmt, argl, arg2, 

wrefresh(Hre're) 
wscanw(a>ire, fmt, argl, arg2, .. 

wsetscrreg(«;m, t, b) 
wstandend (win ) 
wstandout (win ) 



) 



Change all of win 

Turn off debugging trace output 

Turn on debugging trace output 

Use file descriptor fd to check type-ahead 

Printable version of ch 

Add char to win 

Add string to win 

Turn off attrs in win 

Turn on attrs in win 

Set attrs in win to attrs 

Clear win 

Clear to bottom of win 

Clear to end of fine on win 

Delete char from win 

Delete fine from win 

Erase win 

Get a char through win 

Get a string through win 

Get char at current (y, x) in win 

Insert char into win 

Insert line into win 

Set current (y , x) co-ordinates on win 

Refresh but no screen output 

) 

printf ( ) on wire 

Make screen look like win 

scanf ( ) through win 
Set scrolling region of win 
Clear standout attribute in win 
Set standout attribute in win 



Terminfo Level Routines 

These routines should be called by programs that need to deal directly with the terminfo(A) database. Due 
to the low level of this interface, its use is discouraged. Initially, setupterm( ) should be called to define 
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the set of terminal-dependent variables defined in terminfo(4). The header files <curses.h> and 
<term.h> should be included to get the definitions for these strings, numbers, and flags. Parameterized 
strings should be passed through tparm ( ) to instantiate them. All terminfo(4) strings (including the out- 
put of tparmO) should be printed with tputs() orputp(). Before exiting, reset term () should be 
called to restore the tty modes. (Programs desiring shell escapes or suspending with control-Z can call 
resett erm ( ) before the shell is called and f ixterm ( ) after returning from the shell.) 



f ixtermO 

resettermO 

setupt erm (term, fd, re) 



tparm (sir, pi, p2, ..., p9) 
tputs (str, affent, putc ) 

putp (str ) 

vidput s ( attrs , putc ) 



Restore tty modes for terminfo use (called by setupt erm ( ) ) 

Reset tty modes to state before program entry 

Read in database. Terminal type is the character string term, all out- 
put is to HP-UX System file descriptor fd. A status value is returned 
in the integer pointed to by re: 1 is normal. The simplest call would 
be setupterm(0, 1, ) which uses all defaults. 

Instantiate string str with parms p ■ . 

Apply padding info to string str. affent is the number of lines affected, 
or 1 if not applicable, putc ( ) is a putchar-like function to which 
the characters are passed, one at a time. 

A handy function that calls tputs (str, 1 , putchar ) . 

output the string to put terminal in video attribute mode attrs, which 
is any combination of the attributes listed below. Chars are passed to 
putchar-like function putc ( ) . 



vidattr (attrs) 

se t_curt erm ( term ) 

de l_cu r t e rm ( term ) 



Like vidputs but outputs through putchar 
Set the database pointed to by term 
Free the space pointed to by term 

Termcap Compatibility Routines 

These routines were included as a conversion aid for programs that use termcap. Calling parameters are 
the same as for termcap. They are emulated using the terminfo(4) database. Their use in new software is 
not recommended because they might be deleted in future HP-UX releases. 

tget ent ( bp , name ) look up termcap entry for name 

tgetflag(td) get boolean entry for id 

t getnum ( id ) get numeric entry for id 

tget st r ( id , area ) get string entry for id 

tgot o (cap , col , row ) apply parms to given cap 

tputs (cap , affent , fn) apply padding to cap calling fn as putchar 

Attributes 

The following video attributes can be passed to the functions attron ( ) , attrof f ( ) , and attrset ( ) . 

Terminal's best highlighting mode 

Underlining 

Reverse video 

Blinking 

Half bright 

Extra bright or bold 

Blanking (invisible) 

Protected 

Alternate character set 

NLS Attributes 

The following NLS attributes might be returned by inch ( ) : 

A_PIRSTOP2 First byte of 16-bit character 

A_SECOP2 Second byte of 16-bit character 

Function Keys 

The following function keys could possibly be returned by getch if keypad has been enabled. Note that not 
all of these are currently supported due to lack of definitions in terminfo or the terminal not transmitting a 



A_STANDOUT 

A_UNDERLINE 

A_REVERSE 

A_BLINK 

A_DIM 

A_BOLD 

A_BLANK 

A_PROTECT 

A ALTCHARSET 
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unique code when the key is pressed. 



Name 


Value 


Key name 




KEY_BREAK 


0401 


break key (unreliable) 




KEY DOWN 


0402 


The four arrow keys ... 




KEY_UP 


0403 






KEY LEFT 


0404 






KEY_RIGHT 


0405 






KEY_HOME 


0406 


Home key (upward+left arrow) 




KEY BACKSPACE 


0407 


backspace (unreliable) 




KEY FO 


0410 


Function keys. Space reserved for up to 64 


keys. 


KEY_F(n) 


(KEY_F0+ 


(n)) 
Formula for fn. 




KEY_DL 


0510 


Delete line 




KEY IL 


0511 


Insert line 




KEY_DC 


0512 


Delete character 




KEY IC 


0513 


Insert char or enter insert mode 




KEY_EIC 


0514 


Exit insert char mode 




KEY CLEAR 


0515 


Clear screen 




KEY_EOS 


0516 


Clear to end of screen 




KEY EOL 


0517 


Clear to end of line 




KEY_SF 


0520 


Scroll 1 line forward 




KEY SR 


0521 


Scroll 1 line backwards (reverse) 




KEY_NPAGE 


0522 


Next page 




KEY PPAGE 


0523 


Previous page 




KEY_STAB 


0524 


Set tab 




KEY CTAB 


0525 


Clear tab 




KEY_CATAB 


0526 


Clear all tabs 




KEY ENTER 


0527 


Enter or send (unreliable) 




KEY_SRESET 


0530 


soft (partial) reset (unreliable) 




KEY RESET 


0531 


reset or hard reset (unreliable) 




KEY_PRINT 


0532 


print or copy 




KEY LL 


0533 


home down or bottom (lower left) 





Window-Change Signal Support 

All curses routines except the min-curses subset provide SIGWINCH support. Applications that are linked 
with curses routines immediately redraw the screen in response to window size changes. The environmen- 
tal variables LINES and COLUMNS are also updated so that children processes work with the correct win- 
dow size. 

If there is a window size reduction, part of the application display is trimmed. The trimmed portion is 
saved in internal memory at the time of resize. Moreover, this portion is not affected by the application as 
long as it stays invisible. If the application's cursor is trimmed, unexpected behavior results. 

On the other hand, if the window is enlarged, any previously trimmed area is re-displayed (and re- 
activated). If the window is enlarged beyond its initial size, the extra area is padded with blank spaces. 

The default SIGWINCH support can be disabled by installing a custom SIGWINCH signal handler via the 
sigvector command (see sigvector(2)). 

WARNINGS 

HP supports only terminals listed on the current list of HP-supported devices. However, the terminfo(4) 
database may contain information for other terminals besides those that are officially supported. If you use 
such unsupported terminals, they may not work correctly. 

The endwln ( ) routine does not release memory allocated by the lnlt scr ( ) routine. 
Repeated calls to inlt scr ( ) can cause a program to use more memory than was intended. 

Some of these routines call ma Hoc ( ) to allocate memory (see malloc(SC)) and can therefore fail for any 
of the reasons described in the malloc (3C) manual entry. 

SEE ALSO 

sigvector(2), terminfo(4). 
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Using Curses and Terminfo, tutorial in Terminal Control User's Guide. 

STANDARDS CONFORMANCE 

curses ( ) : SVID2, XPG2, XPG3, XPG4 
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NAME 

cuserid() - get character login name of the user 

SYNOPSIS 

#Include <stdio.h> 

char *cuserid(char *s); 

Remarks: 

Because this function behaved differently in previous releases of HP-UX, and behaves differently on other 
systems, its use is not recommended. It is provided only for conformance to current industry standards, 
and is subject to withdrawal in future releases of HP-UX. 

For portability and security, application writers and maintainers should search their existing code and 
replace references to cuserid() with equivalent calls to getpwuld(getuid( ) ), 
getpwuid (geteuid ( ) ) , or get login ( ) , depending on which user name is desired. 

DESCRIPTION 

cuserid( ) generates a character-string representation of the user name corresponding to the effective 
user ID of the process. If s is a NULL pointer, this representation is generated in an internal static area, the 
address of which is returned. Otherwise, s is assumed to point to an array of at least L_cuserid charac- 
ters; the representation is left in this array. The constant L_cuserid is defined in the <stdio.h> 
header file. 

DIAGNOSTICS 

If the login name cannot be found, cuserid ( ) returns a NULL pointer; if s is not a NULL pointer, a null 
character (\0) is placed at s[0]. 

SEE ALSO 

geteuid(2), getlogin(3C) getpwuid(3C). 

STANDARDS CONFORMANCE 

cuserid ( ) : AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

cvtnumO - convert string to floating point number 

SYNOPSIS 

#include <cvtnum.h> 

int cvtnum ( 

^-i^i-to*- nno4 /ma/1 mViov> * a nr*r* 

unsigned char *dst, 

int typ, 

int rnd, 

unsigned char **ptr # 

int *inx 

\ . 

/ 1 

DESCRIPTION 

cvtnum ( ) converts an ASCII character string to a number in one of four floating-point formats: single pre- 
cision, double precision, extended precision, or packed decimal string. 

The string pointed to by src is the string representation of a standard number, an infinity, or a not-a- 
number. A standard number begins with an optional plus or minus sign followed by a string of digits 
optionally containing a decimal point. It can then have an optional e or E followed by an optional sign fol- 
lowed by an integer. Infinities are represented by INF preceded by an optional plus or minus sign. The 
string for a not-a-number is an optional sign followed by NaN followed by any number of hexadecimal 
digits enclosed in parentheses. 

The result is moved to dst and will be of the size and format as defined for the MC6888 1 floating-point 
coprocessor. 

typ indicates the type of conversion to be done. It may be one of four values: C_SNGL, C_DBLE, C_EXT, or 
C_DPACK, indicating single precision, double precision, extended precision and packed decimal string, 
respectively. 

rnd specifies the type of rounding mode and can be one of four values: C_NEAR, C_POS_INF, 
C_NEG_INF, or C_TOZERO, indicating round to nearest, to positive infinity, to negative infinity, or to zero, 
respectively. 

If the value of *ptr is not (char **)NULL, a pointer to the character terminating the scan is returned in the 
location pointed to hyptr. If no number can be formed, *ptr is set to str. 

If inx is not (int *)NULL, cvtnum ( ) uses this to return an indication of the inexactness of the conversion. 
A zero indicates exact; a non-zero value, inexact. 

RETURN VALUE 

If no errors occur or no non-standard conversions are done, cvtnum ( ) returns 0. Otherwise, it returns 
one of the following: 

[C_BADCHAR] Illegal character or unexpected end of string 

[CLOVER] Overflow 

[C.UNDER] Underflow 

[C_INF] Infinity 

[C.QNAN] Quiet NaN 

[C.SNAN] Signalling NaN 

cvtnum ( ) does not use errno when reporting errors. 

SEE ALSO 

scanf(3S), strtod(3C), strtol(3C). 

MC 68881 Floating-Point Coprocessor User's Manual . 
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NAME 

datalock() - lock process into memory after allocating data and stack space 

SYNOPSIS 

ttinclude <sys/lock.h> 

int datalock (size_t datsiz, size_t stsiz); 

DESCRIPTION 

datalock ( ) allocates at least datsiz bytes of data space and stsiz bytes of stack space, then locks the pro- 
gram in memory. The data space is allocated by malloc ( ) (see malloc(3C)). After the program is locked, 
this space is released by free ( ) (see malloc(3C)), making it available for use. This allows the calling pro- 
gram to use that much space dynamically without receiving the SIGSEGV signal. 

The effective user ID of the calling process must be super-user or be a member of or have an effective group 
ID of a group having PRIVJMLOCK access to use this call (see setprivgrp(2)). 

EXAMPLES 

The following call to datalock ( ) allocates 4096 bytes of data space and 2048 bytes of stack space, then 
locks the process in memory: 

datalock (4096, 2048); 

RETURN VALUE 

datalock ( ) returns -1 if malloc ( ) cannot allocate enough memory or if plock ( ) returned an error 
(see plock(2)). 

WARNINGS 

Multiple datalocks cannot be the same as one big one. 

Methods for calculating the required size are not yet well developed. 

AUTHOR 

datalock ( ) was developed by HP. 

SEE ALSO 

getprivgrp(2), plock(2). 
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NAME 

dbminit, fetch, store, delete, firstkey, nextkey, dbmclose - database subroutines 

SYNOPSIS 

int dbmclose (void) ; 

DESCRIPTION 

These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 
1024 bytes)) databases and can locate a keyed item in one or two file system accesses. This package is 
superseded by the newer ndbm(8X) library, which can manage multiple databases. The functions can be 
accessed by giving the - ldbm option to ld(l) or cc(l). 

key and content parameters are described by the datum type. A datum specifies a string of dsize bytes 
pointed to by dptr. Arbitrary binary data, as well as normal ASCII strings, are allowed. The database is 
stored in two files. One file is a directory containing a bit map of keys and has .dir as its suffix. The 
second file contains all data and has . pag as its suffix. 

Before a database can be accessed, it must be opened by dbminit. At the time of this call, the files 
file. d.ir and file .pag must exist. (An empty database is created by creating zero-length .dir and 
. pag files.) 

Once open, data stored under a key is accessed by fetch , and data is placed under a key by store . Storing 
data on an existing key replaces the existing data. A key (and its associated contents) is deleted by 
delete. A linear pass through all keys in a database can be made, in (apparently) random order by using 
firstkey and nextkey. firstkey returns the first key in the database. With any key, nextkey 
returns the next key in the database. The following code can be used to traverse the database: 

for (key = firstkeyO; key. dptr != NULL; key = nextkey (key) ) 

A database can be closed by calling dbmclose . A currently open database must be closed before opening 
a new one. 

DIAGNOSTICS 

All functions that return an int indicate errors with negative values and success with zero. Functions 
that return a datum indicate errors with a null dptr. 

WARNINGS 

The dbm functions provided in this library should not be confused in any way with those of a general- 
purpose database management system such as ALLBASE/HP-UX SQL. These functions do not provide for 
multiple search keys per entry, they do not protect against multi-user access (in other words they do not 
lock records or files), and they do not provide the many other useful data base functions that are found in 
more robust database management systems. Creating and updating databases by use of these functions is 
relatively slow because of data copies that occur upon hash collisions. These functions are useful for appli- 
cations requiring fast lookup of relatively static information that is to be indexed by a single key. 

The . pag file will contain holes so that its apparent size is about four times its actual content. Some older 
UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal 
means (such as cp(l), cat (1), tar(l\ or ar(l)) without expansion. 

dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. 

The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). 
Moreover, all key/content pairs that hash together must fit on a single block, store returns an error if a 
disk block fills with inseparable data. 

delete does not physically reclaim file space, although it does make it available for reuse. 

The order of keys presented by firstkey and nextkey depends on a hashing function, not on anything 
interesting. 

A store or delete during a pass through the keys by firstkey and nextkey may yield unex- 
pected results. 

AUTHOR 

dbm(SX) was developed by the University of California, Berkeley. 

SEE ALSO 

ndbm(3X). 
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NAME 

devnm - map device ID to file path 

SYNOPSIS 

ttinclude <devnm.h> 

int devnm ( 

mode_t devtype, 
dev_t devid, 
char *path, 
size t T-, athlen 
int cache 
); 

DESCRIPTION 

Given a device type, a device ID, and a string in which to return the result, devnm ( ) maps the type and ID 
to a block or character special file (device file) name by searching /dev. It returns in path the full path 
name of the first special file encountered with a matching device type and ID. It searches /dev and all its 
subdirectories recursively in unspecified order. 

The parameters are: 

devtype One of the file type values S_IPBLKor S_IPCHR documented in stat (5). Bits other than 
those in the S_IFMT set are ignored. Hence the value can be, for example, an st_mode 
value returned by st at ( ) (see stat(2)). 

devid A device ID (major/minor) such as returned by stat ( ) in the st_dev or st_rdev 
field. 

path Pointer to the buffer in which to return the path name result. 

pathlen Tells the available length of the path string, including the NUL terminator character. If 
path is too short to hold the full path name, only the first pathlen-1 characters are 
returned in a null-terminated string, and the return value is altered (see below). 

cache A flag that tells devnm ( ) whether to save file information in malloc ( ) 'd memory, and 
later, whether to use that saved information instead of searching /dev again. A subse- 
quent call with cache non-zero can be much faster, especially if /dev is a large tree. How- 
ever, the first call with cache true might be slower because devnm ( ) must read all of the 
/dev tree once to create the cache, rather than returning immediately upon finding a 
matching file. Any call with cache set to zero ignores the cache, if any, and reads the direc- 
tory. 

To allow for possible future enhancements, cache should be restricted to the values and 1. 

There is no way to tell devnm ( ) to free its cached memory. 

devnm ( ) ignores unreadable directories and files for which stat ( ) fails. 

devnm ( ) does not examine alternate (hidden) elements of context-dependent files (CDFs). 

RETURN VALUE 

devnm ( ) returns one of the following values: 

Successful. The result is in path. 

-1 f tw( ) failed, errno contains the value returned from f tw() . path might be altered if 

cache is set. If cache was set for the first time, devnm ( ) freed any memory allocated by the 
current call. 

-2 No matching special file was found, errno is undefined, path is unaltered. 

-3 A matching special file was found, but the name was truncated to fit in path, errno is 

undefined. 

If malloc ( ) fails, devnm ( ) silently abandons the attempt to do caching in the current or any later call 
with cache true, and frees any memory allocated by the current call. 
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AUTHOR 

devnm ( ) was created by HP. 

SEE ALSO 

devnm(lM), stat(2), ftw(3), malloc(3), ttyname(3), stat(5). 
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NAME 

dial( ), undial( ) - establish an out-going terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (CALL call); 
void undial(int fd) ; 

DESCRIPTION 

dial ( ) returns a file-descriptor for a terminal line open for read/write. The argument to dial ( ) is a 
CALL structure (defined in the <dial .h> header file). 

When finished with the terminal fine, the calling program must invoke undial ( ) to release the sema- 
phore that has been set during the allocation of the terminal device. 

The definition of CALL in the <dial . h> header file is: 

pointer to termio attribute struct */ 
transmission data rate */ 
212A modem: low=300, high=12 00 */ 
device name for out-going line */ 
pointer to tel-no digits string */ 
specify modem control for direct lines */ 
Will hold the name of the device used 
to make a connection */ 
The length of the device used to 
make connection */ 
} CALL; 

CALL elements are as follows: 

speed Intended only for use with an outgoing dialed call, in which case its value should be 

either 300 or 1200 to identify the 113A modem, or the high- or low-speed setting on the 
212A modem. Note that the 113A modem or the low-speed setting of the 212A modem 
transmits at any rate between and 300 bits per second. However, the high-speed set- 
ting of the 2 12 A modem transmits and receives at 1200 bits per second only. 

baud Desired transmission baud rate. For example, one might set baud to 110 and speed to 

300 (or 1200). However, if speed set to 1200 baud must be set to high (1200). 

line If the desired terminal line is a direct fine, a string pointer to its device-name should be 

placed in the line element in the CALL structure. Legal values for such terminal device 
names are kept in the Devices file. In this case, the value of the baud element need 
not be specified as it will be determined from the Devices file. 

telno A pointer to a character string representing the telephone number to be dialed. Such 

numbers can consist only of symbols described below. The termination symbol is sup- 
plied by the dial ( ) function, and should not be included in the telno string passed to 
dial ( ) in the CALL structure. 



typedef struct 


{ 






struct 


termio 


*attr; 


/ 


int 






baud; 


/ 


int 






speed; 


/ 


char 






♦line; 


/ 


char 






*telno; 


/ 


int 






modem; 


/ 


char 






♦device; 


/ 


int 






dev_len; 


/ 



Permissible codes 


0-9 


dial 0-9 


* or : 


dial* 


#or; 


dial* 


- 


4-second delay for second dial tone 


e or < 


end-of-number 


w or = 


wait for secondary dial tone 


f 


flash off hook for 1 second 



modem Specifies modem control for direct lines. Set to non-zero if modem control is required. 

attr Pointer to a termio structure, as defined in the <termio.h> header file. A NULL 

value for this pointer element can be passed to the dial ( ) function, but if such a 
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device 
dev len 



structure is included, the elements specified in it are set for the outgoing terminal line 
before the connection is established. This is often important for certain attributes such 
as parity and baud-rate. 

Holds the device name (cul..) that establishes the connection. 

Length of the device name that is copied into the array device. 



INTRPT 


-1 


/* 


D HUNG 


-2 


/* 


NO_ANS 


-3 


/* 
/ 


ILL_BD 


-4 


/* 


A_PROB 


-5 


/* 


L PROB 


-6 


/* 


NO_Ldv 


-7 


/* 


DV NT A 


-8 


/* 


DV_NT_K 


-9 


/* 


NO_BD A 


-10 


/* 


NO_BD_K 


-11 


/* 



RETURN VALUE 

On failure, a negative value indicating the reason for the failure is returned. Mnemonics for these negative 
indices as listed here are defined in the <dlal . h> header file. 

/* interrupt occurred */ 
/* dialer hung (no return from write) */ 
no answer witnin 10 seconds *' 
illegal baud-rate */ 

automatic call unit (acu) problem (open() failure) */ 
line problem (open() failure) */ 
can't open LDEVS file */ 
requested device not available */ 
requested device not known */ 
no device available at requested baud */ 
no device known at requested baud */ 

WARNINGS 

Including the <dial . h> header file automatically includes the <termio . h> header file. 

The above routine uses <stdio . h>, which causes unexpected increases in the size of programs that other- 
wise do not use standard I/O. 

DEPENDENCIES 

HP Clustered Environment 

dial ( ) is not supported on client nodes of an HP Cluster. 

Series 300/400 

An alarm () (see alarm(2)) system call for 3600 seconds is made (and caught) within the dial() 
module for the purpose of "touching" the LCK . . file and constitutes the device allocation semaphore for 
the terminal device. Otherwise, uucp(l) may simply delete the LCK. . entry on its 90-minute clean-up 
rounds. The alarm may go off while the user program is in a read ( ) or write ( ) system call, causing 
an apparent error return. If the user program expects to be around for an hour or more, error returns from 
reads should be checked for (errno==EINTR) , and the read possibly reissued. 

FILES 

/usr/lib/uucp/Devices 

/usr/ spool /uucp/LCK. My-device 

SEE ALSO 

uucp(l), alarm(2), read(2), write(2), termio(7). 

UUCP tutorial in Remote Access User's Guide. 
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NAME 

opendir(), readdir(), telldir(), seekdirO, rewinddir(), closedirO - directory operations 

SYNOPSIS 

#include <dirent.h> 

DIR *opendir (const char *dirname); 

struct dirent *readdir(DIR *dirp); 

long int telldir (DIR *dirp); 

void seekdir(DIR *dirp, long lnt loc); 

void rewinddlr(DIR *dirp); 

int closedir(DIR *dirp); 

DESCRIPTION 

This library package provides functions that allow programs to read directory entries without having to 
know the actual directory format associated with the file system. Because these functions allow programs 
to be used portably on file systems with different directory formats, this is the recommended way to read 
directory entries. 



opendir() 

readdir () 

telldir () 
seekdir ( ) 



opens the directory dirname and associates a directory stream with it. opendir ( ) 
returns a pointer used to identify the directory stream in subsequent operations, open- 
dir ( ) uses malloc(3C) to allocate memory. 

returns a pointer to the next directory entry. It returns a NULL pointer upon reaching the 
end of the directory or detecting an invalid seekdirO operation. See dirent(5) for a 
description of the fields available in a directory entry. 

returns the current location (encoded) associated with the directory stream to which dirp 
refers. 

sets the position of the next readdir ( ) operation on the directory stream to which dirp 
refers. The loc argument is a location within the directory stream obtained from 
telldir(). The position of the directory stream is restored to where it was when 
telldir () returned that loc value. Values returned by telldir () are valid only 
while the DIR pointer from which they are derived remains open. If the directory stream 
is closed and then reopened, the telldir ( ) value might be invalid. 

resets the position of the directory stream to which dirp refers to the beginning of the direc- 
tory. It also causes the directory stream to refer to the current state of the corresponding 
directory, as a call to opendir ( ) would have done. 

closedir ( ) closes the named directory stream, then frees the structure associated with the DIR 
pointer. 



rewinddir() 



RETURN VALUE 

opendir (), 



readdir (), 

telldir(), 
seekdirO 



upon successful completion, returns a pointer to an object of type DIR referring to an open 
directory stream. Otherwise, it returns a NULL pointer and sets the global variable 
errno to indicate the error. 

upon successful completion, returns a pointer to an object of type struct dirent 
describing a directory entry. Upon reaching the end of the directory, readdir ( ) returns 
a NULL pointer and does not change the value of errno. Otherwise, it returns a NULL 
pointer and sets errno to indicate the error. 

upon successful completion, returns a long value indicating the current position in the 
directory. Otherwise it returns -land sets errno to indicate the error. 

does not return any value, but if an error is encountered, errno is set to indicate the 
error. 



closedir ( ) , upon successful completion, returns a value of 0. Otherwise, it returns a value of -1 and 
sets errno to indicate the error. 
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ERRORS 

opendir ( ) fails if any of the following conditions are encountered: 

[BACCES] Search permission is denied for a component of dirname, or read permission is 

denied for dirname. 

[EFAULT] dirname points outside the allocated address space of the process. The reliable 

detection of this error is implementation dependent. 

[ELOOP] Too many symbolic links were encountered in translating the path name. 

[EMFILE] Too many open file descriptors are currently open for the calling process. 

[ENAMETOOLONG] A component of dirname exceeds PATH_MAX bytes, or the entire length of dir- 
name exceeds PATH_MAX - 1 bytes while _POSIX_NO_TRUNC is in effect. 

[ENFILE] Too many open file descriptors are currently open on the system. 

[ENOENT] A component of dirname does not exist. 

[ENOMEM] ma Hoc ( ) failed to provide sufficient memory to process the directory. 

[ENOTDIR] A component of dirname is not a directory. 

[ENOENT] The dirname argument points to an empty string. 

readdir ( ) might fail if any of the following conditions are encountered: 

[EBADF] dirp does not refer to an open directory stream. 

[ENOENT] The directory stream to which dirp refers is not located at a valid directory 

entry. 

[EFAULT] dirp points outside the allocated address space of the process, 

telldir ( ) might fail if any of the following conditions are encountered: 

[EBADF] dirp does not refer to an open directory stream. 

[ENOENT] dirp specifies an improper file system block size, 

seekdir ( ) might fail if the following condition is encountered: 

[ENOENT] dirp specifies an improper file system block size, 

closedir ( ) might fail if any of the following conditions are encountered: 

[EBADF] dirp does not refer to an open directory stream. 

[EFAULT] dirp points outside the allocated address space of the process, 

rewinddir ( ) might fail if any of the following conditions are encountered: 

[EBADF] dirp does not refer to an open directory stream. 

[EFAULT] dirp points outside the allocated address space of the process. 

EXAMPLES 

The following code searches the current directory for an entry name: 

DIR *dirp; 

struct dirent *dp; 

dirp = opendir ("."); 

while ((dp = readdir (dirp) ) != NULL) { 

if (strcmp(dp->d_name, name) ==0) { 
(void) closedir (dirp) ; 
return FOUND; 
} 
} 

(void) closedir (dirp) ; 
return NOT_POUND; 
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WARNINGS 

readdir ( ) and get di rent ries ( ) (see getdirentries(2) are the only ways to access remote NFS direc- 
tories. Attempting to read a remote directory via NFS by using read( ) returns -1 and sets errno to 
EISDIR (see read(2)). 

APPLICATION USAGE 

The header file required for these functions and the type of the return value from readdir ( ) has been _ 

changed for compatibility with System V Release 3 and the XI Open Portability Guide. See ndir(5) for a I 

description of the header file <ndir . h>, which is provided to allow existing HP-UX applications to compile B 

unmodified. 

New applications should use the <dirent .h> header file for portability to System V and X/Open systems. 

AUTHOR 

directory was developed by AT&T, HP, and the University of California, Berkeley. 

SEE ALSO 

close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). 

STANDARDS CONFORMANCE 

closedir ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
opendir ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

readdir ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 
rewinddir ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

seekdir ( ) : AES, XPG2, XPG3, XPG4 
telldir ( ) : AES, XPG2, XPG3, XPG4 



HP-UX Release 9.0: August 1992 - 3 - 457 



div(3C) 



div(3C) 



I 



NAME 

div(), ldiv() - integer division and remainder 

SYNOPSIS 

#include <stdlib.h> 

div_t div(int numer, int denom) ; 

ldiv_t ldiv(long int numer, long int denom); 

DESCRIPTION 

div ( ) Computes the quotient and remainder of the division of the numerator numer by the 

denominator denom. If the division is inexact, the sign of the resulting quotient is that of 
the algebraic quotient, and the magnitude of the resulting quotient is the largest integer 
less than the magnitude of the algebraic quotient. If the result can be represented, the 
result is returned in a structure of type div_t (defined in <stdlib.h>) having 
members quot and rem for the quotient and remainder respectively. Both members have 
type int and values such that quot x denom + rem = numer. If the result cannot be 
represented, the behavior is undefined. 

ldiv ( ) Similar to div ( ) , except that the arguments each have type long int and the result is 

returned in a structure of type ldiv_t (defined in <stdlib.h>) having long int 
members quot and rem for the quotient and remainder respectively. 

WARNINGS 

Behavior is undefined if denom is zero. 

SEE ALSO 

fioor(3M). 

STANDARDS CONFORMANCE 

div ( ) : AES, XPG4, ANSI C 

ldiv ( ) : AES, XPG4, ANSI C 
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NAME 

drand48(), erand48(), lrand48(), nrand48(), mrand48(), jrand48(), srand48(), seed48(), lcong48() - gen- 
erate uniformly distributed pseudo-random numbers 

SYNOPSIS 

#include <stdlib.h> 

double drand48 (void) ; 

double erand4 8 (unsigned short int xsubi[3]); 

long int lrand.4 8 (void.) $ 

long int nrand4 8 (unsigned short int xsubi[3]); 

long int mrand48 (void) ; 

long int jrand4 8 (unsigned short int xsubi[3]); 

void srand48(long int seedval) ; 

unsigned short int *seed4 8 (unsigned short int seedl6v[3]); 

void lcong4 8 (unsigned short int param[7]); 

DESCRIPTION 

This family of functions generates pseudo-random numbers using the well-known linear congruential algo- 
rithm and 48-bit integer arithmetic. 

In the following discussion, the formal mathematical notation [0.0, 1.0) indicates an interval including 0.0 
but not including 1.0. 

drand4 8 ( ) and erand4 8 ( ) return non-negative double-precision floating-point values uniformly distri- 
buted over the interval [0.0, 1.0). 

Irand48 ( ) and nrand48 ( ) return non-negative long integers uniformly distributed over the interval 
[0, 2 31 ). 

mrand48() and jrand48() return signed long integers uniformly distributed over the interval 

[-2 81 , 2 31 ). 

srand4 8 ( ) , seed48 ( ) , and lcong48 ( ) are initialization entry points, one of which should be invoked 
before either drand4 8 ( ) , lrand48 ( ) , or mrand48 ( ) is called. (Although it is not recommended prac- 
tice, constant default initializer values are supplied automatically if drand48(), lrand48(), or 
mrand4 8 ( ) is called without a prior call to an initialization entry point.) erand4 8 ( ) , nrand4 8 ( ) , and 
j rand4 8 ( ) do not require an initialization entry point to be called first. 

All the routines work by generating a sequence of 48-bit integer values, X t , according to the linear 
congruential formula 

X n+1 = (aX n + c) mod m n >0 

The parameter m = 2 48 ; hence 48-bit integer arithmetic is performed. Unless lcong48() has been 
invoked, the multiplier value a and the addend value c are given by 

a = 5DEECE66D 16 = 273673163155 8 
c=B 16 = 13 8 . 

The value returned by any of the functions drand48(), erand48(), lrand48(), nrand48(), 
mrand4 8 ( ) , or j rand4 8 ( ) is computed by first generating the next 48-bit X t in the sequence. Then the 
appropriate number of bits, according to the type of data item to be returned, are copied from the high-order 
(leftmost) bits of X t and transformed into the returned value. 

The functions drand48 ( ) , lrand48 ( ) , and mrand48 ( ) store the last 48-bit X t generated in an inter- 
nal buffer; that is why they must be initialized prior to being invoked. The functions erand48(), 
nrand4 8 ( ) , and j rand4 8 ( ) require the calling program to provide storage for the successive X t values 
in the array specified as an argument when the functions are invoked. That is why these routines do not 
have to be initialized; the calling program merely has to place the desired initial value of X t into the array 
and pass it as an argument. By using different arguments, erand4 8 ( ) , nrand4 8 ( ) , and j rand4 8 ( ) 
allow separate modules of a large program to generate several independent streams of pseudo-random 
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numbers; i.e., the sequence of numbers in each stream do not depend upon how many times the routines 
have been called to generate numbers for the other streams. 

The initializer function srand4 8 ( ) sets the high-order 32 bits of X { to the 32 bits contained in its argu- 
ment. The low-order 16 bits of X, are set to the arbitrary value 330E 16 . 

The initializer function seed48 ( ) sets the value of X t to the 48-bit value specified in the argument array. 
In addition, the previous value of X t is copied into a 48-bit internal buffer, used only by seed48 ( ) , and a 
pointer to this buffer is the value returned by seed4 8 ( ) . This returned pointer, which can just be ignored 
if not needed, is useful if a program is to be restarted from a given point at some future time - use the 
pointer to get at and store the lastX; value, and then use this value to reinitialize via seed48 ( ) when 
the program is restarted. 

The initialization function lcong48 ( ) allows the user to specify the initial X:, the multiplier value a, and 
the addend value c. Argument array elements param [0-2] specify X h param [3-5] specify the multiplier a, 
and param[6] specifies the 16-bit addend c. After lcong4 8 ( ) has been called, a subsequent call to either 
srand4 8 ( ) or seed48 ( ) restores the "standard" multiplier and addend values, a and c, specified above. 

SEE ALSO 

rand(3C). 

STANDARDS CONFORMANCE 



drand4 8 ( ) 
erand4 8 ( ) 

jrand48() 
lcong4 8 ( ) 

lrand48() 
mrand4 8 ( ) 

nrand4 8 ( ) 



AES, SVID2, XPG2, XPG3, XPG4 
AES, SVID2, XPG2, XPG3, XPG4 

AES, SVID2, XPG2, XPG3, XPG4 
AES, SVID2, XPG2, XPG3, XPG4 

AES, SVID2, XPG2, XPG3, XPG4 
AES, SVID2, XPG2, XPG3, XPG4 

AES, SVID2, XPG2, XPG3, XPG4 



seed4 8 ( ) : AES, SVID2, XPG2, XPG3, XPG4 
srand4 8 ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

ecvt(), fcvt,() gcvt,() nl_gcvt() - convert floating-point number to string 

SYNOPSIS 

char *ecvt (double value, size_t ndlgit, lnt *decpt, lnt *sign) ; 

char *fcvt (double value, size_t ndigit, int *decpt, lnt *sign) ; 

char *gcvt (double value, size_t ndiglt, char *buf ) ; 

char *nl_gcvt (double value, slze_t ndlgit, char *buf, int langid); 

DESCRIPTION 

ecvt ( ) Converts value to a null-terminated string of ndigit digits and returns a pointer to the string. 
The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The 
position of the radix character relative to the beginning of the string is stored indirectly 
through decpt (negative means to the left of the returned digits). The radix character is not 
included in the returned string. If the sign of the result is negative, the word pointed to by 
sign is non-zero, otherwise it is zero. 

One of three non-digit characters strings could be returned if the converted value is out of 
range. A - - or + + is returned if the value is larger than the exponent can contain, and is 
negative, or positive, respectively. The third string is returned if the number is illegal, a zero 
divide for example. The result value is Not A Number (NAN) and would return a ? character. 

f cvt ( ) Identical to ecvt ( ) , except that the correct digit has been rounded for printf %f (Fortran 
F-format) output of the number of digits specified by ndigit. 

gcvt ( ) Converts the value to a null-terminated string in the array pointed to by buf and returns buf. 
It produces ndigit significant digits in Fortran F-format if possible, or E-format otherwise. A 
minus sign, if required, and a radix character is included in the returned string. Trailing zeros 
are suppressed. The radix character is determined by the currently loaded NLS environment 
(see setlocale(3C)). If setlocaleO has not been called successfully, the default NLS 
environment, "C", is used (see lang(5)). The default environment specifies a period ( . ) as the 
radix character. 

nl_gcvt ( ) 

differs from gcvt ( ) only by first calling langinit () (see nl_init(SC)) to load the NLS 
environment according to the language specified by langid. 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category determines the value of the radix character within the current NLS environ- 
ment. 

WARNINGS 

The values returned by ecvt ( ) and f cvt ( ) point to a single static data array whose content is 
overwritten by each call. 

nl_gcvt ( ) is provided for historical reasons only; its use is not recommended. 

AUTHOR 

ecvt() and fcvt() were developed by AT&T. gcvt ( ) was developed by AT&T and HP. 
nl_gcvt ( ) was developed by HP. 

SEE ALSO 

setlocale(3C), printf(3S), hpnls(5), lang(5). 

STANDARDS CONFORMANCE 

ecvt ( ) : XPG2 

f cvt ( ) : XPG2 
gcvt ( ) : XPG2 
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NAME 

end, etext, edata - last locations in program 

SYNOPSIS 

extern void *_end, *end / *_etext, *etext, *_edata, *edata; 

DESCRIPTION 



bols _etext and etext is the first address above the program text, the address of _edata and 
edata is the first address above the initialized data region, and the address of _end and end is the first 
address above the uninitialized data region. 

The linker defines these symbols with the appropriate values if they are referenced by the program but not 
denned. The linker issues an error if the user attempts to define _etext, _edata, or _end. 

When execution begins, the program break (the first location beyond the data) coincides with _end, but the 
program break can be reset by the routines of brk(2), malloc (3C), standard input/output (stdio (3S)), the 
profile (-p) option of cc(l), and so on. Thus, the current value of the program break should be determined 
by sbrk(O) (see brk(2)). 

WARNINGS 

In C, these names must look like addresses. Thus, use &end instead of end to access the current value of 
end. 

DEPENDENCIES 

Series 700 and 800: 

The linker defines the following two symbols: 

_text_start The beginning address of the program's text area. 

_data_start The beginning address of the program's data area. 

SEE ALSO 

cc(l), ld(l), brk(2), crt0(3), malloc(3C), stdio(3S). 

STANDARDS CONFORMANCE 

end: XPG2 

edata: XPG2 
etext: XPG2 
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NAME 

erf, erfc - error function and complementary error function 

SYNOPSIS 

#include <math.h> 

double erf (double x) ; 
double erfc (double x) ; 

DESCRIPTION 

erf ( ) returns the error function of x t defined as: 

\7t o 

erfc(), which returns 1.0 - erf (a;), is provided because of the extreme loss of relative accuracy if 
erf (x) is called for large x and the result subtracted from 1.0 (for example, for x = 5, twelve places are 
lost). 

erf ( ) returns 1.0 when x is +INFINITY , or -1.0 when x is -INFINITY . 

erfc ( ) returns 0.0 when x is +INFINITY , or 2.0 when x is -INFINITY . 

ERRORS 

erf ( ) and erfc ( ) return NaN and set errno to EDOM when x is NaN. 

SEE ALSO 

isinf(3M), isnan(3M), exp(3M). 

STANDARDS CONFORMANCE 

erf ( ) in libm.a: AES, SVID2, XPG2, XPG3 
erf ( ) in libM.a: AES, XPG3, XPG4 

erfc ( ) in libm.a: AES, SVID2, XPG2, XPG3 
erfc ( ) in libM.a: AES, XPG3, XPG4 
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NAME 

error_$c_get_text - return subsystem, module, and error texts for a status code 

SYNOPSIS 
C Syntax 

void error_$c_get_text ( 
status_$t status, 
char * subsys, 
long subsysmax, 
char * module, 
long modulemax, 
char * error, 
long errormax) 

Pascal Syntax 

procedure error_$c_get_text ( 
in status'. status_$t; 
out subsysi univ char; 
in subsysmax i integer32; 
out module: univ char; 
in modulemax: integer32; 
out error: univ char; 
in errormax: integer32); 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

The error_$c_get_text ( ) call returns predefined text strings that describe the subsystem, the 
module, and the error represented by a status code. The strings are null terminated. 

status 

A status code in status_$t format. 

subsys 

A character string. The subsystem represented by the status code. 

subsysmax 

The maximum number of bytes to be returned in subsys. 

module 

A character string. The module represented by the status code. 

modulemax 

The maximum number of bytes to be returned in module. 

error 

A character string. The error represented by the status code. 

errormax 

The maximum number of bytes to be returned in error . 

EXAMPLE 

The following statement returns text strings for the subsystem, module, and error represented by the status 
code st: 

error_$c_get_text (st, subsys, MAX, module, MAX, error, MAX); 

SEE ALSO 

error_$c_text(3). 



464 - 1 - HP-UX Release 9.0: August 1992 



error_$c_text(3) error_$c_text(3) 



NAME 

error_$c_text - return an error message for a status code 

SYNOPSIS 
C Syntax 

char *error_$c_text ( 
status_$t status, 
char * message, 
int messagemax) 

Pascal Syntax | 

procedure error_$c_text ( "~ 

in status: status_$t; 
out message: univ char; 
in messagemax: integer32); 

Remarks 

To view this manual entry via the mare(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

error_$c_text ( ) returns a nuU-terminated error message for reporting the completion status of a call. 
The error message is composed from predefined text strings that describe the subsystem, the module, and 
the error represented by the status code. 

status A status code in status_$t format. 

message A character string. The error message represented by the status code. 

messagemax The maximum number of bytes to be returned in message. 

EXAMPLE 

The following statement returns an error message for reporting the status code st : 

error_$c_text (st, message, MAX); 

SEE ALSO 

error_$c_get_text(3). 
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NAME 

error_$intro - error text database operations 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

error_$ ( ) calls convert status codes into textual error messages, and include: 

error_$c_get_text ( ) 

Return subsystem, module, and error texts for a status code. 

error_$c_text ( ) 

Return an p.rrnr message fnr a status code. 



There is no header file for the error_$ ( ) calls. They can be declared as follows: 

extern void error_$c_get_text ( ) ; 
extern char *error_$c_text () ; 

error_$ ( ) calls use the status_$t data type, which is defined in <idl/c/nbase .h>. 

Data Types 

error_$ ( ) calls take as input a status code in status_$t format. 

status_$t A status code. Most NCS calls supply their completion status in this format. The 
status_$t type is defined as a structure containing a long integer: 

struct status_$t { 
long all; 
} 

However, the calls can also use status_$t as a set of bit fields. To access the 
fields in a returned status code, assign the value of the status code to a union defined 
as follows: 

typedef union { 
struct { 

unsigned fail : 1, 
subsys : 1 , 
mode : 8 ; 
short code; 
} s; 

long all; 
} status_u; 

all All 32 bits in the status code. If all is equal to status_$ok, the call that sup- 

plied the status was successful. 

fail If this bit is set, the error was not within the scope of the module invoked, but 

occurred within a lower-level module. 

subsys This indicates the subsystem that encountered the error. 

mode This indicates the module that encountered the error. 

code This is a signed number that identifies the type of error that occurred. 

SEE ALSO 

error_$c_get_text(3), error_$c_text(3) . 
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NAME 

exp, log, loglO, log2, pow, sqrt, cbrt - exponential, logarithm, power, square root, cube root functions 

SYNOPSIS 

#include <math.h> 

double exp (double x) ; 

double log (double x) ; 

double loglO (double x) ; 

double log2 (double x) ; 

double pow(double x, double y) ; 

double sqrt (double x) ; 

double cbrt (double x) ; 

float expf (float x) ; 

float logf (float x) ; 

float loglOf (float x) ; 

float log2f (float x) ; 

float powf (float x, float y) ; 

float sqrtf (float x) ; 

float cbrtf (float x) ; 

DESCRIPTION 

exp ( ) returns e x . 

log ( ) returns the natural logarithm of a:. The value of x must be positive. 

logl ( ) returns the logarithm base ten of*. The value of a; must be positive. 

log2 ( ) returns the logarithm base two of*. The value of a; must be positive. 

pow ( ) returns a?. If a; is 0.0, y must be positive. If a; is negative, y must be an integer. 

sqrt ( ) returns the non-negative square root of a;. The value of x must not be negative. 

cbrt ( ) returns the cube root of x. The value of a; must not be negative. 

expf ( ) , logf ( ) , loglOf ( ) , log2f ( ) , powf ( ) , sqrtf ( ) , and cbrtf ( ) are float versions of 
exp ( ) , log ( ) , loglO ( ) , log2 ( ) , pow ( ) , sqrt ( ) , and cbrt ( ) ; they take float arguments and 
return float results. Their performance is significantly faster than that of the double versions of the 
functions. Programs must be compiled in ANSI mode (with the - Aa option) in order to use these functions; 
otherwise, the compiler promotes the float arguments to double, and the functions return incorrect 
results. 

DEPENDENCIES 
Series 300/400 

log2 ( ) , cbrt ( ) , expf ( ) , logf ( ) , loglOf ( ) , log2f ( ) , powf ( ) , sqrtf ( ) , and cbrtf ( ) are 
not supported on Series 300/400 systems. 

Series 700/800 

log2 (), cbrt(), expf (), logf (), loglOf (), log2f (), powf (), sqrtf (), and cbrtf () are 
not specified by any standard (however, the float functions are named in accordance with the conven- 
tions specified in the "Future Library Directions" section of the ANSI C standard). These functions are pro- 
vided in the PAl.l versions of the math library only. The +DA1 . 1 option (default on Series 700 systems) 
links in a PAl.l version automatically. A PAl.l library can also be finked in explicitly. For more informa- 
tion, see the HP-UX Floating-Point Guide. 

/lib/libm.a 

exp ( ) returns: 
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log( 
pow( 



pow( 
pow( 



sqrt 

/lib/libM 

exp( 



log( 
pow( 
pow( 



pow( 
pow( 



sqrt 



ERRORS 
/lib/libm 

exp( 



log( 



+INFINITY when re is +INFINITY, 

0.0 when re is -INFINITY. 
, log2 ( ) , and loglO ( ) return +INFINITY when x is +INFINITY. 
returns +INFINITY when: 

Absolute value of re is greater than 1.0 and} 1 is +INFINITY, 

Absolute value of re is less than 1.0 andy is -INFINITY, 

x is +INFINITY andy is greater than 0.0, or 

x is -INFINITY andy is an even integer. 

returns -INFINITY when a; is -INFINITY andy is an odd integer, 
returns 0.0 when: 

Absolute value of a; is greater than 1.0 andy is -INFINITY, 

Absolute value of re is less than 1.0 andy is +INFINITY, 

x is +INFINITY andy is less than 0.0. 
) and cbrt ( ) return +INFINITY when x is +INFINITY. 

.a 

returns: 

+INFINITY when re is +INFINITY, 

0.0 when re is -INFINITY. 
, log2 ( ) , and loglO ( ) return +INFINITY when re is +INFINITY. 
returns 1.0 when re andy are both 0.0. 
returns +INFINITY when: 

Absolute value of re is greater than 1.0 andy is +INFINITY, 

Absolute value of re is less than 1.0 and y is -INFINITY, 

re is +INFINITY andy is greater than 0.0, or 

re is -INFINITY and y is an even integer. 

returns -INFINITY when re is -INFINITY andy is an odd integer, 
returns 0.0 when: 

Absolute value of re is greater than 1.0 andy is -INFINITY, 

Absolute value of re is less than 1.0 andy is +INFINITY, 

x is +INFINITY andy is less than 0.0. 
) and cbrt() return +INFINITY when re is +INFINITY. 



returns HUGE_VAL when the correct value would overflow, or 0.0 when the correct value would 



underflow, and sets errno to ERANGE. NaN is returned and errno is set to EDOM when re is NaN. 



, log2 (), and logl0() return -HUGE_VAL and set errno to EDOM when re is non-positive. 



NaN is returned and errno is set to EDOM when re is NaN or -INFINITY. A message indicating DOMAIN 
error (or SING error when re is 0.0) is printed on the standard error output in these cases. 

pow ( ) returns 0.0 and sets errno to EDOM when x is 0.0 and y is negative, or when re is negative and y is 
not an integer. NaN is returned and errno is set to EDOM when re ory is NaN. In these cases a message 
indicating DOMAIN error is printed on the standard error output. When the correct value for pow() would 
overflow or underflow, pow ( ) returns ±HUGE_VAL or 0.0 respectively, and sets errno to ERANGE. 
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sqrt ( ) returns NaN and sets errno to EDOM when x is negative, NaN or -INFINITY. A message indi- 
cating DOMAIN error is printed on the standard error output. 

cbrt ( ) returns 0.0 and sets errno to EDOM when x is negative. NaN is returned and errno is set to 
EDOM when x is NaN. In these cases a message indicating DOMAIN error is printed on the standard error 
output. When the correct value for cbrt ( ) would overflow or underflow, cbrt ( ) returns ±HUGE_VAL or 
0.0 respectively, and sets errno to ERANGE. 

These error-handling procedures can be changed with the matherr ( ) function (see matherr (SM.)). 

/lib/libM.a 

No error messages are printed on the standard error output. 

exp ( ) returns HUGEJVAL when the correct value would overflow, or 0.0 when the correct value would 
underflow, and sets errno to ERANGE. NaN is returned and errno is set to EDOM when x is NaN. 

log ( ) , log2 ( ) , and loglO ( ) return NaN and set errno to EDOM when x is negative, -INFINITY, or 
NaN. -HUGE_VAL is returned and errno is set to EDOM when x is 0.0. 

pow( ) returns -HUGE_VAL and sets errno to EDOM when x is 0.0 and y is negative. NaN is returned 
and errno is set to EDOM when x is negative and y is not an integer or when x or y is NaN. When the 
correct value for pow( ) would overflow or underflow, pow( ) returns ±HUGE_VAL or 0.0 respectively, and 
sets errno to ERANGE. 

sqrt ( ) returns NaN and sets errno to EDOM when x is negative, NaN or -INFINITY. 

cbrt ( ) returns NaN and sets errno to EDOM when x is negative or when x is NaN. When the correct 
value for cbrt ( ) would overflow or underflow, cbrt ( ) returns ±HUGE_VAL or 0.0 respectively, and sets 
errno to ERANGE. 

These error-handling procedures can be changed by using the _matherr ( ) function (see matherr (3M)). 
Note that _matherr ( ) is provided in order to assist in migrating programs from libm.a to libM.a 
and is not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

isinf(3M), isnan(3M), matherr(3M). 

STANDARDS CONFORMANCE 

exp ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
exp ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

log ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
log ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

loglO ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
loglO ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

pow( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
pow ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

sqrt ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
sqrt ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

exportentO, getexportent(), setexportentO, addexportent(), remexportent(), endexportent(), getexportopt() 
- access exported file system information 

SYNOPSIS 

#include <stdio.h> 
ftinclude <exportent .h> 

PILE *setexportent () ; 

struct exportent *getexportent (FILE *f ildep) ; 

int addexportent (PILE *filep, char *dirname, char *optlons); 

int remexportent (PILE *filep, char *dimame); 

char *getexportopt (struct exportent *xent, char *opt); 

void endexportent (PILE *f ilep) ; 

DESCRIPTION 

These routines access the exported filesystem information in /etc/xtab. 

setexportent ( ) Open the export information file and return a file pointer to use with getexpor- 
tent ( ) , addexportent ( ) , remexportent ( ) , and endexportent ( ) . 
Returns NULL if the file is locked or if an error is encountered in opening the file. 

getexportent ( ) Read the next line from filep and return a pointer to an object with the following 
structure containing the broken-out fields of a fine in file /etc/xtab. The fields 
have meanings described in exports(4). 

#define ACCESS_OPT "access" /* machines that can mount fs */ 

#define ROOT_OPT "root" /* machines with root access to fs */ 

ttdefine RO_OPT "ro" /* export read-only */ 

#define ANON_OPT "anon" /* uid for anonymous requests */ 

#define ASYNC_OPT "async" /* all mounts will be aynchronous */ 

struct exportent { 

char *xent_dirname; /* directory (or file) to export */ 

char *xent_options; /* options, as above */ 

}; 

getexportent ( ) returns NULL if it encounters end of file. 

addexportent ( ) Add the exportent to the end of the open file filep. It returns if successful and -1 
on failure. 

remexportent ( ) Remove the indicated entry from the list. Returns on success and -1 on failure. 

getexportopt ( ) Scans the xent_opt ions field of the exportent structure for a substring that 
matches opt. Returns the string value of opt, or NULL if the option is not found. 

endexportent ( ) Close the file. 

RETURN VALUE 

setexportentO, getexportent ( )> and getexportopt ( ) return a NULL pointer on EOF or 
error. 

addexportent ( ) and remexportent ( ) return -1 if they fail. 

WARNINGS 

The returned exportent structure points to static information that is overwritten in each call. 

AUTHOR 

exportent, getexportent () , setexportentO, addexportent () , remexportent () , 
endexportent ( ) , and getexportopt ( ) were developed by Sun Microsystems, Inc. 

FILES 

/etc/exports /etc/xtab 
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SEE ALSO 

exportfs(lM), exports(4). 



I 
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NAME 

fclose(), fflush() - close or flush a stream 

SYNOPSIS 

#lnclude <stdio.h> 

int f close (PILE *stream) ; 
int f flush (FILE *stream) ; 

DESCRIPTION 

f close ( ) causes any buffered data for the named stream to be written out, and the stream to be closed. 
Buffers allocated by the standard input/output system may be freed. 

f close ( ) is performed automatically for all open files upon calling exit(2). 

If stream points to an output stream or an update stream in which the most recent operation was output, 
f flush ( ) causes any buffered data for the stream to be written to that file; otherwise any buffered data is 
discarded. The stream remains open. 

If stream is a null pointer, f f lush ( ) performs this flushing action on all currently open streams. 

RETURN VALUE 

Upon successful completion, f close ( ) and f flush ( ) return 0. Otherwise, they return EOF and set 
errno to indicate the error. 

ERRORS 

fclose() and fflush() fail if: 

[EAGAIN] The O.NONBLOCK flag is set for the file descriptor underlying stream and the process 

would be delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not valid. 

[EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the 

maximum file size (see ulimit(2)). 

[EINTR] f close ( ) or f flush ( ) was interrupted by a signal. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A 

SIGPIPE signal is also sent to the process. 

Additional errno values may be set by the underlying write ( ) , lseek ( ) , and close ( ) func- 
tions (see write(2), lseek(2) and close(2)). 

SEE ALSO 

close(2), exit(2), lseek(2), write(2), fopen(3S), setbuf(3S). 

STANDARDS CONFORMANCE 

f close ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSDC.l, ANSI C 

f flush ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

ferror(), feof(), clearerr() - stream status inquiries 

SYNOPSIS 

ttinclude <stdio.h> 

int f error (PILE *stream) ; 
int f eof (FILE *stream) ; 
void clearerr(PILE *stream); 

DESCRIPTION 

f error ( ) Returns non-zero when an I/O error has previously occurred reading from or writing to the H 

named stream, otherwise zero. Unless cleared by clearerr(), or unless the specific fM 

stdio routine so indicates, the error indication lasts until the stream is closed. 

f eof ( ) Returns non-zero when EOF has previously been detected reading the named input stream, 

otherwise zero. 

clearerr ( ) Resets the error indicator and EOF indicator on the named stream to zero. 

WARNINGS 

All these routines are implemented both as library functions and as macros. The macro versions, which are 
used by default, are denned in <stdio.h>. To obtain the library function, either use a ttundef to 
remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in parentheses or 
use the function address. The following example illustrates each of these methods : 

ttinclude <stdio.h> 
ttundef ferror 



main() 
{ 



}; 



int (*find_error()) (); 
return_val=ferror(fd) ; 
return_val=(feof ) (fdl); 
find_error » feof; 



SEE ALSO 

open(2), fopen(3S). 

STANDARDS CONFORMANCE 

ferror ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

clearerr ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
feof ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

fgetpos(), fsetpos() - save and restore a file position indicator for a stream 

SYNOPSIS 

#include <stdio.h> 

int fgetpos(FILE *stream, fpos_t *jpos); 

int fsetpos(PILE *stream, const fpos_t *pos) ; 

DESCRIPTION 

f getpos ( ) Store the current value of the file position indicator for the stream pointed to by stream in 
the object pointed to by pos. The value stored contains information usable by f set- 
pos ( ) for repositioning the stream to its position at the time of the call to f getpos ( ) . 

f setpos ( ) Set the file position indicator for the stream pointed to by stream according to the value of 
the object pointed to by pos, which must be a value set by an earlier call to f getpos ( ) on 
the same stream. 

A successful call to f setpos ( ) clears the end-of-file indicator for the stream and undoes 
any effects of ungetc(SS) on the same stream. After a f setpos ( ) call, the next operation 
on a update stream can be either input or output. 

RETURN VALUE 

If successful, these functions return zero; otherwise non-zero. 

WARNINGS 

Failure can occur if these functions are used on a file that has not been opened via f open ( ) . In particu- 
lar, they must not be used on a terminal or on a file opened viapopen(3S). 

f setpos ( ) has no effect on streams that are open for append (see fopen(3SJ). 

SEE ALSO 

fseek(3S), fopen(3S), popen(3S), ungetc(3S). 

STANDARDS CONFORMANCE 

f getpos ( ) : AES, XPG4, ANSI C 

f setpos ( ) : AES, XPG4, ANSI C 
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NAME 

fgetws() - get a wide character string from a stream file 

SYNOPSIS 

ttinclude <wchar.h> 

wchar_t *f getws (wchar_t *ws, int n, PILE *stream); 

Remarks: 

This function is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. It 
parallels the 8-bit character I/O function defined io.gets(3S). 

DESCRIPTION 

f getws ( ) Reads characters from the stream, converts them into corresponding wide characters, and 
places them into the array pointed to by ws, until n - 1 characters are read, a new-line 
character is read and transferred to ws, or an end-of-file condition is encountered. The 
wide string is then terminated with a null wide character. 

The definition for this functions and the type wchar_t are provided in the <wchar . h> header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

Upon successful completion, f getws ( ) returns ws. If the stream is at end-of-file, the end-of-file indicator 
for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream 
is set, errno is set to indicate the error, and a null pointer is returned. 

f error ( ) and f eof ( ) can be used to distinguish between an error condition and an end-of-file condition. 

ERRORS 

f getws ( ) fails if data needs to be read into the stream's buffer, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data 

was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its 

controlling terminal, and either the process is ignoring or blocking the SIGTTIN sig- 
nal or the process group of the process is orphaned. 

[EILSEQJ The data obtained from the input stream do not form a valid wide character string. 

Additional errno values can be set by the underlying read ( ) function (see read(2)). 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getwc(3C), fputws(3C), scanf(3S). 

STANDARDS CONFORMANCE 

f getws ( ) : XPG4 
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NAME 

fileno( ) - map stream pointer to file descriptor 

SYNOPSIS 

ttinclude <stdio.h> 

int fileno(PILE *stream) ; 

DESCRIPTION 

f ileno ( ) returns the integer file descriptor associated with the named stream; see open(2). 

The following symbolic values in <unistd. h> define the file descriptors associated with stdin, stdout, 
and stderr when a program is started : 

STDIN_PILENO Value of zero for standard input, stdin. 
STDOUT_FILENO Value of 1 for standard output, stdout. 
STDERR_F ILENO Value of 2 for standard error, stderr. 

RETURN VALUE 

Upon error, f i leno ( ) returns -1. 

SEE ALSO 

open(2), fopen(3S). 

STANDARDS CONFORMANCE 

f ileno ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SDC.1 
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NAME 

floor, ceil, fmod, fabs, rint, fabsf, fmodf - floor, ceiling, remainder, absolute value, and round-to-nearest func- 
tions 

SYNOPSIS 

#include <math.h> 

double floor (double x) ; 

double ceil (double x) ; 

double fmod (double x, double y) ; 

double fabs (double x) ; 

double rint (double x) ; 

float fabsf (float x) ; 

float fmodf (float x, float y) ; 

DESCRIPTION 

floor ( ) returns the largest integer (as a double-precision number) not greater than x . 

ceil ( ) returns the smallest integer not less than x. 

fmod ( ) returns the floating-point remainder (/") of the division of xby y, where /"has the same sign as x, 
such that x =iy +/"for some integer i, and \f\ < \y I . 

fabs ( ) returns the absolute value of x, \x I . 

rint ( ) returns the integer (represented as a double precision number) nearest x in the direction of the 
prevailing rounding mode. 

fabsf () and fmodf () are float versions of f abs ( ) and fmod (); they take float arguments 
and return float results. Their performance is significantly faster than that of the double versions. 
Programs must be compiled in ANSI mode (with the -Aa option) in order to use these functions; otherwise, 
the compiler promotes the float arguments to double, and the functions return incorrect results. 

DEPENDENCIES 
Series 300/400 

fabsf ( ) , fmodf ( ) , and rint ( ) are not supported on Series 300/400 systems. 

Series 700/800 

fabsf ( ) , fmodf ( ) , and rint ( ) are not specified by any standard (fabsf ( ) and fmodf ( ) are, how- 
ever, named in accordance with the conventions specified in the "Future Library Directions" section of the 
ANSI C standard). These functions are provided in the PA1.1 versions of the math library only. The 
+DA1 . 1 linker option (default on Series 700 systems) links in a PAl.l version automatically. A PA1.1 
library can also be linked in explicitly. For more information, see the HP-UX Floating-Point Guide. 

/lib/libm.a 

When a: is INFINITY, floor ( ) , ceil ( ) , and rint ( ) return INFINITY respectively. 

fabs ( ) returns +INFINITY when x is 1INFINITY. 

fmod ( ) returns x if y is 0.0, if xly would overflow, or if xly would underflow (including wheny is UNFIN- 
ITY). 

/lib/LibM.a 

No error messages are printed on the standard error output. 

When re is ±INFINITY, floor ( ) , ceil ( ) , and rint ( ) return INFINITY respectively. 

fabs ( ) returns +INFINITY when* is UNFINITY. 

fmod ( ) returns 0.0 if xly would overflow, or x if xly would underflow (including wheny is iJNFINITY). 

NOTES 

In the default rounding mode (round to nearest), on a machine that conforms to the IEEE-754 standard, 
rint [x ) is the integer nearest x with the additional stipulation that if I rint (x ) -x I =1/2, then 
rint {x ) is even. Other rounding modes can make rint ( ) act like floor ( ) , or like ceil ( ) , or round 
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toward 0. 

Another way to obtain an integer near x is to declare (in C): 

double x; int k; k = x; 

The HP C compiler rounds x toward to get the integer k. Note that if x is larger than k can accommo- 
date, the value of k and the presence or absence of an integer overflow are hard to predict. 

ERRORS 
/lib/libm.a 

floor () and ceil() return NaN and set errno to EDOM when re isNaN. 

f mod ( ) returns NaN and sets errno to EDOM when x or y is NaN, or when x is UNFINITY. 
f abs ( ) returns NaN and sets errno to EDOM when x is NaN. 

/lib/libM.a 

floor ( ) and cell ( ) return NaN and set errno to EDOM when x is NaN. 

f mod ( ) returns NaN and sets errno to EDOM when y is 0.0, when x or y is NaN, or when x is ±INFINITY. 
f abs ( ) returns NaN and sets errno to EDOM when x is NaN. 

SEE ALSO 

abs(3C), isinf(3M), isnan(3M), ieee(3M). 

STANDARDS CONFORMANCE 

f loor ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
floor ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

ceil () in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.1 
ceil () in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

f abs ( ) in libma: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.1 
f abs ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

fmod ( ) in libma: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
fmod ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

fnmatchQ - match filename patterns 

SYNOPSIS 

ttinclude <unistd.h> 

int fnmatch (const char *pattern, const char *string, int flags); 

DESCRIPTION 

fnmatch ( ) performs pattern matching as described in regexp(5) under PATTERN MATCHING NOTATION. 
By default, the rule qualifications for filename expansion do not apply; i.e., periods (dots) and slashes are 
matched as ordinary characters. This default behavior can be modified by using the flags described below. 

The flag argument modifies the interpretation of pattern and string. If FNM_PATHNAME, which is defined 
in <unistd. h>, is set in flag, a slash character in string must be explicitly matched by a slash in pattern; 
it cannot be matched by either the asterisk or question mark special characters or by a bracket expression. 

If PNM_PERIOD is set in flag, a leading period ( . ) must be explicitly matched. It will not be matched by a 
bracket expression, question mark or asterisk. By default, a period is leading if it is the first character in 
string. If FNMJPATHNAME is set in flag, a period is leading if it is the first character in string or immedi- 
ately follows a slash. 

If FNM_NOESCAPE is not set in flag, a backslash character (\) in pattern followed by any other character 
matches that second character in string. In particular, \\ matches a backslash in string. If 
PNM_NOESCAPE is set, a backslash character is treated as an ordinary character. 

If flag is zero, the slash character and the period are treated as regular characters. If flag has any other 
value, the result is undefined. 

RETURN VALUE 

If string matches the pattern specified by pattern, fnmatch () returns zero. Otherwise, fnmatch () 
returns non-zero. 

EXAMPLE 

The following excerpt uses fnmatch ( ) to check each file in a directory against the pattern * . c: 

pattern = "*.c" ; 

while (dp = readdlr (dlrp) ) { 

If ( (fnmatch (pattern, dp->d_name, 0) ) == 0) { 
/* do processing for match */ 

} } 

SEE ALSO 

sh(l), glob(3c). 

STANDARDS CONFORMANCE 

fnmatch ( ) : XPG4, POSIX.2 
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NAME 

fopen(), freopenO, fdopen() - open or re-open a stream file; convert file to stream 

SYNOPSIS 

ttinclude <stdio.h> 

PILE *fopen(const char *pathname, const char *type); 

PILE *freopen( const char *pathname, const char *type, PILE *stream); 

PILE *fdopen(int fildes, const char *type) ; 

DESCRIPTION 

fopen() 



fopen() returns a 



Opens the file named by pathname and associates a stream with it. 
pointer to the PILE structure associated with the stream, 

freopenO substitutes the named file in place of the open stream. The original stream is closed, 
regardless of whether the open ultimately succeeds, f reopen ( ) returns a pointer to the 
PILE structure associated with stream and makes an implicit call to clearerrO (see 
/error(3S)). 

freopenO is typically used to attach the preopened streams associated with stdin, 
stdout, and stderr toother files. 

f dopen ( ) associates a stream with a file descriptor. File descriptors are obtained from open ( ) , 
dup ( ) , creat ( ) , or pipe ( ) (see open(2), dup{2\ creat{2), andpipe(2)), which open files 
but do not return pointers to a FILE structure stream. Streams are necessary input for 
many of the Section (3S) library routines. The type of stream must agree with the mode of 
the open file. The meanings of type used in the f dopen ( ) call are exactly as specified 
above, except that w, w+, wb, and wb+ do not cause truncation of the file. 

pathname Points to a character string containing the name of the file to be opened. 

type Character string having one of the following values: 

r open for reading 

w truncate to zero length or create for writing 

a append; open for writing at end of file, or create for writing 

rb open binary file for reading 

wb truncate to zero length or create binary file for writing 

ab append; open binary file for writing at end-of-file, or create binary file 

r+ open for update (reading and writing) 

w+ truncate to zero length or create for update 

a+ append; open or create for update at end-of-file 

r+b or rb+ open binary file for update (reading and writing) 

w+b or wb+ truncate to zero length or create binary file for update 

a+b or ab+ append; open or create binary file for update at end-of-file 

When a file is opened for update, both input and output can be done on the resulting stream. However, out- 
put cannot be directly followed by input without an intervening call to f flush ( ) or to a file positioning 
function (f seek ( ) , f setpos ( ) , or rewind ( ) ), and input cannot be directly followed by output without 
an intervening call to a file positioning function unless the input operation encounters end-of-file. 

When a file is opened for append (i.e., when type is a or a+), it is impossible to overwrite information 
already in the file. All output is written at the end of the file, regardless of intervening calls to f seek ( ) . 
If two separate processes open the same file for append, each process can write freely to the file without fear 
of destroying output being written by the other. Output from the two processes will be intermixed in the 
file in the order in which it is written. 

RETURN VALUE 

Upon successful completion, fopen(), fdopen(), and freopenO return a FILE * pointer to the 
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stream. Otherwise, a null pointer is returned and errno is set to indicate the error. 

ERRORS 

f open ( ) , f dopen ( ) , and f reopen ( ) fail if: 

[EINVAL] The type argument is not a valid mode. 

[ENOMEM] There is insufficient space to allocate a buffer. 

fopen() and f reopen () fail if: 

[EACCES] Search permission is denied on a component of the path prefix, or the file exists and the 

permissions specified by type are denied, or the file does not exist and write permission is 
denied for the parent directory of the file to be created. 

[EINTR] A signal was caught during f open ( ) or f reopen ( ) . function. 

[EISDIR] The named file is a directory and type requires write access. 

[EMFILE] The calling process has attempted to exceed its open file limit. 

[ENAMETOOLONG] 

The length of the pathname string exceeds PATH_MAX or a pathname component is longer 
than NAME_MAX while POSIX_NO_TRUNC is in effect. 

[ENFILE] The system file table is full. 

[ENOENT] The named file does not exist or the pathname argument points to an empty string. 

[ENOSPC] The directory or file system that would contain the new file cannot be expanded, the file 

does not exist, and it was to be created. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] The named file is a character special or block special file, and the device associated with the 

special file does not exist. 

[EROFS] The named file resides on a read-only file system and type requires write access. 

Additional errno values can be set by the underlying open ( ) call made from the f open ( ) and f reo- 
pen ( ) functions (see open(2)). 

NOTES 

HP-UX binary file types are equivalent to their non-binary counterparts. For example, types r and rb are 
equivalent. 

SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S), popen(3S), setvbuf(3S). 

STANDARDS CONFORMANCE 

f open ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

f dopen ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 

f reopen ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

fpclassifyO, fpclassifyf() - floating-point operand classification functions 

SYNOPSIS 

# include <math.h> 

int fpclassify (double x) ; 
lnt fpclasslfyf (float x) ; 

DESCRIPTION 

fpclassifyO and fpclassifyf ( ) return a non-negative integer value that specifies the IEEE 
operand class to which the argument x belongs. The value returned is one of the following macros which 
are defined in <math . h>: 



#define FP_PLUS_NORM /* 

ttdefine FP_MINUS_NORM 1 /* 

ttdefine FP_PLUS_ZERO 2 /* 

#define FP_MINUS_ZERO 3 /* 

ttdefine FP_PLUS_INF 4 /* 

ttdefine FP_MINUS_INF 5 /* 

ttdefine FP_PLUS_DENORM 6 /* 

ttdefine FP_MINUS_DENORM 7 /* 

ttdefine FP_SNAN 8 /* 

ttdefine FP_QNAN 9 /* 



Positive normalized */ 
Negative normalized */ 
Positive zero */ 
Negative zero */ 
Positive infinity */ 
Negative infinity */ 
Positive denormalized ' 
Negative denormalized * 
Signalling NaN */ 
Quiet NaN */ 



Every possible argument value falls into one of these ten categories, so these functions never result in an 
error. 

fpclassifyf ( ) is the float version of fpclassify ( ) . Programs must be compiled in ANSI mode 
(with the - Aa option) in order to use this function; otherwise, the compiler promotes the f loat argument 
to double, and the function returns incorrect results. 

DEPENDENCIES 
Series 300/400 

fpclassify ( ) and fpclassifyf ( ) are not supported on Series 300/400 systems. 

Series 700/800 

fpclassifyO and fpclassifyf ( ) are provided in the PA1.1 versions of the math library only. The 
+DA1 . 1 option (default on Series 700 systems) finks in a PAl.l version automatically. A PA1.1 library can 
also be linked in explicitly. For more information, see the HP-UX Floating-Point Guide. 

These functions are not specified by any standard. However, they implement the class ( ) function sug- 
gested in the "Recommended Functions and Predicates" appendix of the IEEE-754 floating-point standard. 
Also, fpclassifyf ( ) is named in accordance with the conventions specified in the 
"Future Library Directions" section of the ANSI C standard. 

SEE ALSO 

isnan(3M), isinf(3M), ieee(3M). 
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NAME 

fpgetroundO, fpsetroundQ, fpgetmaskQ, fpsetmask(), fpgetstickyO, fpsetstickyO, fpsetdefaults(), fpgetcon- 
trol(), fpsetcontrolO, fpgetfastmode(), fpsetfastmode() - floating-point mode-control functions 

SYNOPSIS 

# include <math.h> 

fp_md fpgetround (void) ; 

fp_rnd fpset round (fp_rnd mode); 

fp_except fpgetmask(void) ; 

fp_except fpsetmask(fp_except value); 

fp_except fpget sticky (void) ; 

fp_except fpset sticky(fp_except value) ; 

int fpgetfastmode(void) ; 

int fpsetfastmode(int value); 

void f psetdef aults (void) ; 

fp_control fpget control (void) ; 

fp_control fpsetcontrol (fp_control value); 

DESCRIPTION 

The fpgetround ( ) suite of functions allows programmers to manipulate the floating-point control regis- 
ter (also called the floating-point status register). 

fpgetround ( ) returns the current rounding mode. The type of the returned value, f p_rnd, is defined 
as follows in <math . h>: 



typedef enum { 

FP_RZ=0, /* 

FPJRN, /« 

FP_RP, /* 

FPJRM, /* 
} fp_md; 



Round toward zero */ 

Round to nearest */ 

Round toward positive infinity 

Round toward negative infinity 



The default value is PP_RN. Round-to-nearest mode rounds to the representahle value closest to the true 
value. If two representable values are equally close to the true value, the system chooses the one whose 
least significant bit is zero. 

f psetround ( ) sets the rounding mode to the specified value of type f p_rnd and returns the previous 
rounding mode. 

There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and 
invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set 
to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the 
corresponding exception flag is set to 1 and no trap takes place. The exception-trap-enable bits are some- 
times called mask bits; the exception flags are sometimes called sticky bits. The routines f pgetmask ( ) 
and fpgetstickyO return the current settings of these bits. To change the settings of these bits, use 
fpsetmaskO and fpsetstickyO . 

fpgetmaskO returns the current exception trap enable bits. The type of the returned value, 
f p_except, is defined as int in <math . h>. The floating-point exception types are defined as follows in 
<math.h>: 

Invalid operation exception */ 
divide -by- zero exception */ 
overflow exception */ 
underflow exception */ 
imprecise (inexact result) */ 
simply zero to clear all flags */ 



#define 


PP_X_INV 


0x10 


/ 


#define 


PP X DZ 


0x08 


/ 


#define 


PP_X_OPL 


0x04 


/ 


#define 


PP X UPL 


0x02 


/ 


#define 


FP_X_IMP 


0x01 


/ 


#define 


PP_X_CLEAR 


0x00 


/ 
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fpsetmask( ) sets or clears the exception trap enable bits and returns the previous setting. The argu- 
ment is an expression of type f p_except. (To set or clear the exception trap enable bits at compile time, 
use the compiler option +F'Bstring). 

f pgetsticky ( ) returns the current exception flags. 

fpset sticky ( ) sets or clears the exception flags and returns the previous setting. The argument is an 
expression of type f p_except. 

f pgetf astmode ( ) and fpsetfastmodeO allow the programmer to change the way the system han- 
dles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant 
underflow mode. On Series 700/800 systems, underflow involves a fault into the kernel, where the IEEE- 
mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. 
On some PAl.l-based systems, fastmode causes the hardware to simply substitute a zero for the result of an 
operation, with no fault occurring. This may be a significant performance optimization for applications that 
underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they 
were true zero operands. 

f pgetf astmode ( ) returns the current fastmode setting: 1 if fastmode is set, if the default IEEE-754- 
compliant underflow mode is set. On systems that do not support fastmode, this function returns an 
undefined value. 

On systems that support fastmode, fpset fastmode ( ) sets fastmode to either 1 (fastmode) or (IEEE- 
754-compliant underflow mode) and returns the previous setting. On systems that do not support fast- 
mode, this function has no effect. 

f psetdef aults ( ) changes the default environment on Series 700 workstations, which is 

Round to nearest (PP_RN) 

All exception flags cleared (FP_X_CLEAR) 

All exception traps disabled 

Fast underflow mode disabled 

f psetdef aults ( ) changes these defaults to more useful values. Specifically, it enables traps for the 
invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result 
exception traps disabled. It sets the environment as follows: 

Round to nearest (PP_RN) 

All exception flags cleared (PP_X_CLEAR) 

All exception traps enabled except underflow and inexact result (PP_X_INV+PP_X_DZ+PP_X_OPL) 

Fast underflow mode enabled (if the system supports it) 

f pgetcontrol ( ) and fpsetcontrol ( ) access fpO, the floating-point unit's control register (also 
called the status register). 

f pgetcontrol ( ) returns the value of f pO. The type of the returned value, f p_control, is defined as 
long in <math . h>. 

fpsetcontrol ( ) sets the value of f pO and returns the previous value. For the format of f pO, see the 
HP-UX Floating-Point Guide or the PA-RISC 1.1 Architecture and Instruction Set Reference Manual . 

DEPENDENCIES 
Series 300/400 

These functions are not supported on Series 300/400 systems. 

Series 700/800 

All of these functions are provided in the PAl.l versions of the math library only. The +DA1 . 1 linker 
option (default on Series 700 systems) links in a PAl.l version automatically. A PAl.l library can be linked 
in explicitly. For more information, see the HP-UX Floating-Point Guide. 

WARNINGS 

f psetst icky ( ) modifies all exception flags, f psetmask ( ) modifies all exception trap enable bits. 

Both C and Fortran require truncation (rounding to zero) for floating-point to integer conversions. The 
current rounding mode has no effect on these conversions. 
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NAME 

fputwsO - put a wide character string on a stream file 

SYNOPSIS 

ttinclude <wchar.h> 

int fputws (const wchar_t *ws # PILE *stream); 

Remarks: 

This function is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. It 
parallels the 8 bit character I/O function defined in puts(3S). 

DESCRIPTION 

fputws ( ) writes a character string corresponding to the null-terminated wide-character string pointed to 
by ws to the named output stream, but does not append a new-line character or a terminating null charac- 
ter. 

The definition for this function, the type wchar_t and the value WEOP are provided in the <wchar . h> 
header. 

EXTERNAL INFLUENCES 
Locale 

The LC__CTYPE category determines how wide character conversions are done. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

Upon successful completion, fputws ( ) returns a non-negative number. Otherwise it returns WEOP, sets 
the error indicator for the stream, and sets errno to indicate the error. 

ERRORS 

fputws ( ) fails if either the stream is unbuffered, or stream's buffer needed to be flushed causing an 
underlying write ( ) call to be invoked, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the 

maximum file size (see ulimit(2)). 

[EINTR] A signal was caught during the write ( ) system call. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any pro- 

cess. A SIGPIPE signal is also sent to the process. 

[EILSEQ] A wide character in ws does not correspond to a valid character. 

Additional errno values may be set by the underlying write ( ) function (see write(2)). 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putwc(3C). 

NOTES 

fputws ( ) does not append a new-fine character. 

STANDARDS CONFORMANCE 

fputws ( ) : XPG4 
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NAME 

fread(), fwrite() - buffered binary input/output to a stream file 

SYNOPSIS 

ttinclude <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nitems, PILE *stream) ; 
size_t fwrite (const void *ptr, size_t size, size_t nitems, FILE *stream) ; 

DESCRIPTION 

f r ead ( ) copies, into an array pointed to by ptr, nitems items of data from the named input stream, where 
an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length size . f read ( ) 
stops appending bytes if an end-of-file or error condition is encountered while reading stream, or if nitems 
items have been read, f read ( ) leaves the file pointer in stream, if defined, pointing to the byte following 
the last byte read if there is one. f read ( ) does not change the contents of stream. 

fwrite ( ) appends at most nitems items of data from the array pointed to by ptr to the named output 
stream, fwrite ( ) stops appending when it has appended nitems items of data or if an error condition is 
encountered on stream, fwrite ( ) does not change the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof specifies the length of an item 
pointed to by ptr. If ptr points to a data type other than char it should be cast into a pointer to char. 

SEE ALSO 

read(2), write(2), fopen(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), scanf(3S). 

RETURN VALUE 

f read ( ) and fwrite ( ) return the number of items read or written. If size or nitems is non-positive, no 
characters are read or written and is returned by both f read ( ) and fwrite ( ) . 

STANDARDS CONFORMANCE 

f read ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

fwrite ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

frexp(), ldexp(), modfO - split floating-point into mantissa and exponent 

SYNOPSIS 
DESCRIPTION 

Every non-zero number can be written uniquely as x * 2 n , where the "mantissa" (fraction) x is in the range 
0.5 < I x I < 1.0, and the "exponent" n is an integer. 

f rexp ( ) returns the mantissa of a double value, and stores the exponent indirectly in the location 

pointed to by eptr. If value is zero, both results returned by frexp are zero. 

Idexp ( ) returns the quantity value * 2 exp . _ 

modf ( ) returns the signed fractional part of value and stores the integral part indirectly in the | 

location pointed to by iptr. 

DIAGNOSTICS 

If ldexp ( ) would cause overflow, +HUGE is returned (according to the sign of value), and errno is set 
to ERANGE . 

If ldexp ( ) would cause underflow, zero is returned and errno is set to ERANGE. 

STANDARDS CONFORMANCE 

frexp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

ldexp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
modf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l, ANSI C 
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NAME 

fseek(), rewind(), ftell() - reposition a file pointer in a stream 

SYNOPSIS 

ttinclude <stdio.h> 

int fseek(FILE *stream, long int offset, int whence); 
void rewind(FILE *streaia) ; 
long int f tell (FILE *stream) ; 

DESCRIPTION 

f seek ( ) sets the file-position indicator for stream. The new position, measured in bytes from the begin- 
ning of the file, is obtained by adding offset to the position specified by whence. The specified position is the 
beginning of the file for SEEK_SET, the current position for SEEK_CUR, or end-of-file for SEEK_END. 

If the most recent operation, other than f tell ( ) , on the stream is fflushQ, the file offset in the underly- 
ing open file description is adjusted to reflect the location specified by the f seek ( ) . 

rewind [stream) is equivalent to fseek (stream, OL, SEEK_SET), except that no value is 
returned. 

fseek() and rewind () undo any effects of ungetc(3S). 

After fseek ( ) or rewind ( ) , the next operation on a file opened for update can be either input or out- 
put, fseek () clears the EOF indicator for the stream, rewind () does an implicit clearerrO call 
(see ferror(3S)). 

f tell ( ) returns the offset of the current byte relative to the beginning of the file associated with the 
named stream. 

RETURN VALUE 

fseek ( ) returns zero if it succeeds. Otherwise it returns -1 and sets errno to indicate the error. 

f tell ( ) returns the current value of the file position indicator for the stream measured in bytes from the 
beginning of the file. Otherwise, ftell() returns -1 and sets errno to indicate the error. 

rewind () does not return a value. Therefore, any application that needs to detect errors should clear 
errno before calling rewind ( ) . Then, upon completion, if errno is non-zero, it should assume an error 
has occurred. 

ERRORS 

fseek ( ) , f tell ( ) , and rewind ( ) fail if the stream is unbuffered or the buffered data needs to be 
flushed, or if any of the following conditions are encountered: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor and the process would be delayed 

in the write operation. 

[EBADF] The underlying file is not open for writing. 

[EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the 

maximum file size. See ulimit(2). 

[EINTR] A signal was caught during the write operation. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A 

SIGPIPE signal is also sent to the process. 

[ESPIPE] A seek operation was attempted and the file descriptor underlying stream is associ- 

ated with a pipe. 

fseek ( ) also fails if: 
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[EINVAL] The whence argument is invalid, or the file-position indicator would be set to a nega- 

tive value. 

Additional errno values may be set by the underlying write ( ) and lseek( ) functions (see write(2) 
and lseek(2)). 

WARNINGS 

On HP-UX systems, the offset returned by f tell ( ) is measured in bytes and it is permissible to seek to 
positions relative to that offset. However, when porting to non-HP-UX systems, fseek() should be used 
directly without relying on any offset obtained from f tell ( ) because arithmetic cannot meaningfully be 
performed on such an offset if it is not measured in bytes on a particular operating system. 

fseek() and rewind () have no effect on streams that have been opened in append mode (see I 

fopen(3S)). ■ 

SEE ALSO 

lseek(2), write(2), ferror(3S), fopen(3S), fgetpos(3S), ungetc(3S). 

STANDARDS CONFORMANCE 

f seek ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

f tell ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
rewind ( ) : AES, SVTD2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
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NAME 

ftw, ftwh, nftw, nftwh - walk a file tree 

SYNOPSIS 

#include <ftw.h> 

lnt ftw (char *path, int (*fn)(), 
int ftwh (char *path, int (*fn)(), 
int nftw (char *path, int (*fn)(), 
int nftwh (char *path, int (*fn)(), 

DESCRIPTION 

ftw() recursively descends the director^ hierarchy rooted in nath. For each, obiect in the hierarchy, 
ftw ( ) calls fn, passing it a pointer to a null-terminated character string containing the name of the object, 
a pointer to a stat structure containing information about the object (see stat(2)\ and an integer. Possi- 
ble values of the integer, defined in the <f tw . h> header file, are: 

PTW_F The object is a file. 

PTW_D The object is a directory, 

FTWJDNR The object is a directory without read permission, fn will not be called for any of its 

descendants. 

PTW_NS stat ( ) could not successfully be executed on the object. The contents of the stat 

structure is undefined. If the stat ( ) failure is because the object is in a directory 
without search permission, fn is called and the walk continues. If stat ( ) fails for 
any other reason, ftw ( ) does not call/h, sets errno, and returns -1. 

Tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some 
error is detected within ftw() (such as an I/O error). If the tree is exhausted, ftw() returns zero. 11 fn 
returns a non-zero value, f tw( ) stops its tree traversal and returns whatever value was returned by fn. 
If ftw ( ) detects an error, it returns -1 and sets the error type in errno. 

f tw( ) visits a directory before visiting any of its descendants. 

f tw( ) , ftwh ( ) , nf tw( ) , and nftwh ( ) use one file descriptor for each level in the tree. The depth 
argument limits the number of file descriptors that can be used. If depth is or negative, the effect is the 
same as if it were 1. depth must not be greater than the number of file descriptors currently available for 
use. For best performance, depth should be at least as large as the number of levels in the tree. 

ftwh() is eqivalent to ftw() except that ftwh() also traverses hidden directories (context dependent 
files — see cdf(4)). 

nf tw( ) is similar to f tw( ) except that it takes the additional argument flags. The flags field is the 
inclusive OR of the following values, as defined in the <f tw. h> header file: 

FTWJPHYS nf tw ( ) does a physical walk. It does not follow symbolic links, nf tw ( ) fol- 

lows hard links but does not walk down any path that crosses itself. If 
FTW_PHYS is not specified nftw ( ) follows symbolic and hard links but does 
not walk a path that crosses itself. 

FTW_MOUNT The walk does not cross a mount point. This means the walk does not visit any 

files that reside on a device other than the one where the walk started. It does 
not cross NFS mount points. 

FTW_DEPTH nftw() performs a depth-first search. This means that a directory's contents 

are visited before the directory itself is visited. 

FTW_CHDIR The walk does a chdir ( ) (see chdir(2)) to each directory before reading it. 

FTW_CDF The walk traverses hidden directories (context dependent files — see cdf(4)). 

FTW_SERR The walk normally terminates and returns -1 if stat ( ) fails for any reason. 

If FTW_SERR is specified and a stat ( ) failure is encountered, fn is called, 
and the walk continues. 
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nf tw( ) calls fn with four arguments for each file and directory visited. The first argument is the path- 
name of the file or directory, the second is a pointer to a stat structure (see stat(2)) containing informa- 
tion about the object, and the third is an integer giving additional information as follows: 

The object is a file. 

The object is a directory. 

The object is a directory and subdirectories have been visited. This can be passed to 
fn only if FTW_DEPTH is specified. 

The object is a symbolic link. This can be passed to fn only if F TW_PHYS is specified. 

The object is a directory that cannot be read, fn is not called for any of its descen- 
dants. 

stat ( ) failed on the object. The contents of the stat structure passed to fn are 
undefined. If the stat ( ) failure occured because the object is in a directory without 
search permission, er mo is set, and nftw() returns -1 after calling fn . Note that 
this behavior differs from f tw( ) . If stat ( ) fails for any other reason, nf tw( ) 
does not call fn, sets errno, and returns -1. This behavior can be altered by 
specifingthe FTW_SERR /Zag . 

The fourth argument is a structure FTW which contains the following members: 

int base; 
int level; 

The value of base is the offset from the first character in the pathname to where the basename of the object 
starts; this pathname is passed as the first argument to fn. The value of level indicates depth relative to 
the start of the walk, where the start level has a value of zero. 

nftwh() is equivalent to nftw() except that nftwh() also traverses hidden directories (context 
dependent files — see cdf(4d). nftwh() is equivalent to calling nftw() with the FTW_CDF flag 
specified. 

ERRORS 

f tw ( ) , f twh ( ) , nf tw ( ) , and nf twh ( ) fail if any of the following conditions are encountered: 

[EACCES] If a component of the path prefix denies search permission or read permission is 

denied for path, and fit returns -1 and does not reset errno. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENOENT] path points to the name of a file that does not exist, or points to an empty string. 

[ENOTDIR] A component of path is not a directory. 

[EINVAL] The value of the depth argument is invalid. 

In addition, if the function pointed to by fn encounters system errors, errno may be set accordingly. 

WARNINGS 

On Series 300, 400 and 700 systems, f tw ( ) uses lstat ( ) instead of stat ( ) to get the structure con- 
taining information about the object (f tw( ) uses stat ( ) on Series 800 systems). See stat{2). 

Because these functions are recursive, it is possible for them to terminate with a memory fault when 
applied to very deep file structures. 

ftw(), ftwh(), nftw(), and nftwh() use malloc() to allocate dynamic storage during their 
operation. If they are forcibly terminated (such as if longjmp ( ) is executed by fn or an interrupt rou- 
tine) the calling function will not have a chance to free that storage, causing it to remain allocated until the 
process terminates. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and 
arrange to have fn return a nonzero value at its next invocation. 

AUTHOR 

f tw ( ) , f twh ( ) , nf tw ( ) , and nf twh were developed by AT&T and HP. 
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SEE ALSO 

stat(2), malloc(3C), cdf(4). 

STANDARDS CONFORMANCE 

f tw( ) : AES, SVID2, XPG2, XPG3, XPG4 



I 
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NAME 

gamma(), lgamma(), signgam() - log gamma function 

SYNOPSIS 

# include <math.h> 

double gamma (double x) ; 
double 1 gamma (double x) ; 
extern lnt signgam; 

DESCRIPTION 

gamma ( ) and lgamma ( ) return In ( | T (x ) | ) , where T (x) is defined as 



]e- t t*- 1 dt. 



The sign of T(x) is returned in the external integer signgam. The argument x must not be a non-positive 
integer, (gamma ( ) is defined over the reals excluding the non-positive integers). 

The following C program fragment can be used to calculate T: 

if ( (Y = gamma (x)) > LN_MAXDOUBLE ) 

error ( ) ; 
y = signgam * exp(y); 

where ify is greater than LN_MAXDOUBLE, as defined in the <values . h> header file, exp ( ) returns a 
range error (see exp(3M)). 

ERRORS 
/lib/libm.a 

For non-positive integer arguments, gamma ( ) and lgamma ( ) return HUGE_VAL and set errno to 
EDOM. A message indicating SING error is printed on the standard error output. 

If the correct value would overflow, gamma () and lgamma () return HUGE_VAL and set errno to 
ERANGE. 

gamma ( ) and lgamma ( ) return NaN and set errno to EDOM when x is NaN, or return +INFINITY and 
set errno to EDOM when x is dtlNFINITY. A message indicating DOMAIN error is printed on the standard 
error output. 

These error-handling procedures can be changed by using the matherr ( ) function (see matherr(3M)). 

/Lib/LibM.a 

No error messages are printed on the standard error output. 

For non-positive integer arguments gamma ( ) and lgamma ( ) return HUGE_VAL and set errno to 
EDOM. A message indicating SING error is printed on the standard error output. 

If the correct value would overflow, gamma () and lgamma () return HUGE_VAL and set errno to 
ERANGE. 

gamma ( ) and lgamma ( ) return NaN and set errno to EDOM when x is NaN, or return +INFINITY and 
set errno to EDOM when x is INFINITY. 

These error-handling procedures can be changed by using the _matherr ( ) function (see matherr(3Mj). 
Note that _matherr ( ) is provided in order to assist in migrating programs from libm.a to libM.a 
and is not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

exp(3M), isinf(3M), isnan(3M), matherr(3M), values(5). 

STANDARDS CONFORMANCE 

gamma ( ) in libm.a: AES, SVID2, XPG2, XPG3 
gamma ( ) in libM.a: AES, XPG3, XPG4 

lgamma ( ) in libm.a: AES, XPG3 
lgamma ( ) in libM.a: AES, XPG3, XPG4 



HP-UX Release 9.0: August 1992 - 1 - 493 



gamma (3M) gamma (3M) 



signgam in libm.a: AES, SVID2, XPG2, XPG3 
signgam in libM.a: AES, XPG3, XPG4 



I 
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NAME 

getc(), getchar(), fgetc(), getw() - get character or word from a stream file 

SYNOPSIS 

#include <stdio.h> 

int getc (PILE *stream) ; 
int getchar(void) ; 
int fgetc(FILE *stream); 
int getw(PILE *stream) ; 

DESCRIPTION 

getc ( ) Returns the next character (i.e., byte) from the named input stream, as an unsigned charac- 

ter converted to an integer. It also moves the file pointer, if defined, ahead one character in 
stream. getcharO is defined as getc (stdin) . getc() and getchar() are 
defined both as macros and as functions. 

fgetc() Same as getc(), but is a function rather than a macro. fgetc() is slower than 

getc ( ) , but it takes less space per invocation and its name can be passed as an argument 
to a function. 

getw ( ) returns the next word (i.e., int in C) from the named input stream, getw ( ) increments 

the associated file pointer, if defined, to point to the next word. The size of a word is the 
size of an integer and varies from machine to machine, getw ( ) assumes no special 
alignment in the file. 

RETURN VALUE 

Upon sucessful completion, getc(), getcharO, and fgetc() return the next byte from the input 
stream pointed to by stream (stdin for get char ( ) ). If the stream is at end-of-file, the end-of-file indica- 
tor for the stream is set and EOF is returned. If a read error occurs, the error indicator for the stream is set, 
errno is set to indicate the error, and EOF is returned. 

Upon sucessful completion, getw( ) returns the next word from the input stream pointed to by stream. If 
the stream is at end-of-file, the end-of-file indicator for the stream is set and getw( ) returns EOF. If a 
read error occurs, the error indicator for the stream is set, and getw ( ) returns EOF and sets errno to 
indicate the error. 

f error ( ) and f eof ( ) can be used to distinguish between an error condition and an end-of-file condition. 

ERRORS 

getc ( ) , getchar ( ) , getw ( ) , and f get c ( ) fail if data needs to be read into the stream's buffer, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data 

was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its 

controlling terminal, and either the process is ignoring or blocking the SIGTTIN sig- 
nal or the process group of the process is orphaned. 

Additional errno values may be set by the underlying read() function (see read (2)). 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). 

WARNING 

getc ( ) and getchar ( ) are implemented both as library functions and macros. The macro versions, 
which are used by default, are defined in <s tdio . h>. To obtain the library function either use a ttundef 
to remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in parenthesis or 
use the function address. The following example illustrates each of these methods : 
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#include <stdio.h> 
#undef getc 

main() 
{ 

int (*get_char()) (); 

retum_val=getc (c, £d) ; 

return_val=(getc) (c,fdl) ; 

get_char = get char; 

}; 

If the integer value returned by getc ( ) , getchar ( ) , or f getc ( ) is stored into a character variable 
then compared against the integer constant EOF, the comparison may never succeed because sign-extension 
of a character on widening to integer is machine- dependent. 

The macro version of getc ( ) incorrectly treats a stream argument with side effects. In particular, 
getc(*f+ + ) does not work sensibly. The function version of getc ( ) or fgetc() should be used 
instead. 

Because of possible differences in word length and byte ordering, files written using putw ( ) are machine- 
dependent, and may be unreadable by getw ( ) on a different processor. 

STANDARDS CONFORMANCE 

getc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

f getc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
getchar ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
getw ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

getccent(), getcccid(), getccnam(), setccent(), endccent(), fgetccentO - get HP Cluster configuration entry 

SYNOPSIS 

#include <cluster.h> 

struct cct_entry *getccent (void) ; 

struct cct_entry *getcccid(cnode_t cid) ; 

struct cct_entry *getccnam( const char *name) ; 

void setccent (void) ; 

void endccent (void) ; 

struct cct_entry *fgetccent (filb *stream) ; 

DESCRIPTION 

getccent ( ) , getcccid ( ) , and getccnam( ) each return a pointer to an object with the following 
structure containing the broken-out fields in the /etc /c lust erconf file. The file contains a fist of 
cct_entry structures, defined in the <cluster .h> header file. The cct_entry structure includes 
the following fields: 

u_char machine_id[M_IDLEN] ; /* Unique machine ID */ 
cnode_t cnode_id; /* cnode ID */ 

char cnode_name[15] ; /* cnode name */ 
char cnode_type; /* 'r'=cluster server 

' c'=all other cluster nodes */ 
cnode_t swap_serving_cnode; /* swap cnode */ 
int kcsp; /* default number of CSPs 

to create see csp(lM) */ 

The constant M_IDLEN is defined in <c luster .h>. 

getccent ( ) When first called, getccent ( ) opens the cluster configuration file 

/etc/clusterconf and returns a pointer to the first cct_entry structure in 
the file. Thereafter, it returns a pointer to the next cct_entry structure in the file. 
Successive calls can be used to search the entire file. 

getcccid ( ) Searches from the beginning of the file until an entry whose cnode ID matches cid is 

found, and returns a pointer to the particular structure in which it was found. 

getccnam( ) Searches from the beginning of the file until a cnode name matching name is found 

and returns a pointer to the particular structure in which it was found. If an EOF or 
an error is encountered on reading, these functions return a NULL pointer. 

setccent ( ) Has the effect of rewinding the cluster configuration file to the beginning of the file to 

allow repeated searches. 

endccent ( ) Can be called to close the cluster configuration file when processing is complete. 

f getccent ( ) Returns a pointer to the next cct_entry structure in the stream stream, which 

matches the format of /etc/clusterconf. 

RETURN VALUE 

A NULL pointer is returned on EOF or error. 

WARNINGS 

The above routines use <stdio.h>, which causes them to increase the size of programs not otherwise 
using standard I/O, more than might be expected. 

All information is contained in a static area that is overwritten with each call; thus information must be 
copied if it is to be saved. 

AUTHOR 

getccent ( ) was developed by HP. 

FILES 

/etc/clusterconf 
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SEE ALSO 

csp(lM), clusterconf(4). 
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NAME 

getcdf(), hidecdfQ - manipulate CDF path names 

SYNOPSIS 

ttinclude <unistd.h> 

char *getcdf (const char *path, char *buf, size_t size); 
char *hidecdf (const char *path, char *buf, size_t size); 

DESCRIPTION 

getcdf ( ) and hideedf ( ) manipulate path names possibly containing CDF (hidden directory) com- 
ponents. 

getcdf ( ) Returns a pointer to the expanded path matching the path name in path. The path argu- 
ment can be a context dependent file (CDF) in which case a path name with all hidden direc- 
tories expanded is returned. If path is not a CDF, a copy of the original path name is 
returned. 

hideedf ( ) Returns a pointer to the simplified path corresponding to path. Any context-dependent 
components in the original path that match the current context (see context^)) are removed 
from the resulting path. 

The value of size must be at least one greater than the length of the path name to be returned. 

If buf is not a NULL pointer, getcdf ( ) and hideedf ( ) copy the expanded path name into array buf. 
If buf is a NULL pointer, getcdf ( ) and hideedf ( ) obtain size bytes of space using malloc() (see 
malloc(3C)). In this case, the pointer returned by getcdf () and hideedf ( ) can be used as an argu- 
ment in a subsequent call to free() (see malloc(3C)). 

RETURN VALUE 

Upon successful completion, getcdf ( ) and hideedf ( ) return a pointer to the resulting path name. 
Otherwise, a value of NULL is returned and errno is set to indicate the error. 

ERRORS 

If either getcdf()or hideedf () fails, it will set errno to one of the following values: 

[ENOENT] A component of path does not exist. 

[EACCES] Read or search permission is denied for one of the directories given in path. 

[ENAMETOOLONG] size is not large enough to hold the resulting path. 

EXAMPLES 

#include <stdio.h> 

char *path, *cdf, *getcdf(); 
int size; 

if ((cdf = getcdf (path, NULL, size)) == NULL) { 

perror ( "getcdf " ) ; 

exit(l); 
} 

printf ("%s\n", cdf); 
free (cdf) ; 

AUTHOR 

getcdf ( ) and hideedf ( ) were developed by HP. 

SEE ALSO 

showcdf(l), malloc(3C), cdf(4), context(5). 
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NAME 

getclock - get current value of system-wide clock 

SYNOPSIS 

#include <sys/timers ,h> 

int getclock(int clock_type, struct timespec *tp); 

DESCRIPTION 

getclock ( ) gets the current value tp of the specified system-wide clock, clockjype. 

ge t c lock ( ) supports a clockjype of TIMEOFDAY, denned in <sys / 1 imer s . h> which clock represents 
the time-of-day clock for the system. For this clock, the values returned by getclock ( ) represent the 
amount of time since the Epoch. 

RETURN VALUE 

getclock ( ) returns a value of zero if successful; otherwise it returns a value of -1 and sets errno to 
indicate the error. 

ERRORS 

getclockQ fails if any of the following conditions are encountered: 

[EINVAL] clockjype does not specify a known system- wide clock. 

[EIO] An error occurred while accessing the clock device. 

SEE ALSO 

gettimer(3C), setclock(3C), <sys/timers.h>. 

STANDARDS CONFORMANCE 

getclock():AES 
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NAME 

getcwd(), gethcwdO - get pathname of current working directory 

SYNOPSIS 

ttinclude <unistd.h> 

char *getcwd(char *buf, size_t size); 
char *gethcwd(char *buf, size_t size); 

DESCRIPTION 

getcwd ( } places the absolute pathname of the current working directory in the array pointed to by buf, 
and returns buf. The value of size must be at least one greater than the length of the pathname to be 
returned. 

If buf is a NULL pointer, getcwd() obtains size bytes of space using mallocO (see malloc(3C)). In this 
case, the pointer returned by getcwd ( ) can be used as the argument in a subsequent call to free ( ) 
(see malloc(&Q). Invoking getcwd ( ) with buf as a null pointer is not recommended because this func- 
tionality may be removed from the HP-UX operating system in a future release. 

gethcwd ( ) works the same as getcwd ( ) except the returned directory pathname lists all hidden direc- 
tories (context dependent files (see cdf(4)). 

RETURN VALUE 

Upon successful completion, getcwd ( ) returns a pointer to the current directory pathname. Otherwise, it 
returns NULL with er mo set if size is not large enough, or if an error occurs in a lower-level function. 

ERRORS 

getcwd ( ) fails if any of the following conditions are encountered: 

[EINVAL] The size argument is zero or negative. 

[ERANGE] The size argument is greater than zero, but is smaller than the length of the 

pathname. 

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length 
of a component of the path name exceeds NAME_MAX bytes while 
_POSIX_NO_TRUNC is in effect. 

getcwd ( ) may fail if any of the following conditions are encountered: 

[EACCES] Read or search permission is denied for a component of pathname. 

[EFAULT] buf points outside the allocated address space of the process, getcwd () may 

not always detect this error. 

[ENOMEM] ma 1 loc ( ) failed to provide size bytes of memory. 

EXAMPLES 

char *cwd, *getcwd(); 
char buf [PATH_MAX+ 1 ] ; 

if ((cwd = getcwd((buf *)NULL, PATH_MAX+1)) == NULL) { 

perror ("pwd" ) ; 

exit(l); 
} 
puts (cwd) ; 

AUTHOR 

getcwd ( ) was developed by AT&T, gethcwd ( ) was developed by HP. 

SEE ALSO 

pwd(l), malloc(3C), cdf(4). 

STANDARDS CONFORMANCE 

getcwd ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
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NAME 

getdate() - convert user format date and time 

SYNOPSIS 

#include <time.h> 

struct tm *getdate (const char *string) ; 
extern int getdate_err; 

DESCRIPTION 

getdate ( ) converts user definable date and/or time specifications pointed to by string into a struct 
tm. The structure declaration is in the <time ,h> header file (see ctime(SC)). 

User-supplied templates are used to parse and interpret the input string. The templates are text, files 
created by the user and identified via the environment variable DATEMSK. DATEMSK should be set to 
indicate the full pathname of the template file. The first line in the template that matches the input 
specification is used for interpretation and conversion into the internal time format. Upon successful com- 
pletion, getdate () returns a pointer to a struct tm; otherwise, it returns NULL and the external 
variable getdate_err is set to indicate the error. 

The following field descriptors are supported: 

%% same as % 

%a abbreviated weekday name 

%A full weekday name 

%b abbreviated month name 

%B full month name 

%c locale's appropriate date and time representation 

%d day of the month (01 through 31; the leading is optional) 

%e same as %d 

%D date as %m/%d/%y 

Ssh abbreviated month name 

%H hour (00 through 23) 

%1 hour (01 through 12) 

Ssm month number (01 through 12) 

SsM minute (00 through 59) 

%n same as \n 

%p locale's equivalent of either AM or PM 

%r time as %I:%M:%S %p 

%R time as %H:%M 

%S seconds (00 through 59) 

%t insert a tab 

%T time as %H:%M:%S 

%vr weekday number (Sunday = through Saturday = 6) 

%x. locale's appropriate date representation 

%X locale's appropriate time representation 

%Y year without century (00 through 99) 

%Y year as ccyy (e.g., 1986) 

%7i time zone name or no characters if no time zone exists 

Month and weekday names can consist of any combination of uppercase and lowercase letters. The user 
can request that the input date or time specification be in a specific language by setting the LC_TIME 
category (see setlocale(SC)). 

For descriptors that allow leading zeros, leading zeros are optional; not required. However, the number of 
digits used for those descriptors must not exceed two, including leading zeros. Extra whitespace in either 
the template file or in string is ignored. 

The field descriptors %c, %x., and %X are not supported if they include unsupported field descriptors. 

The following example shows the possible contents of a template: 

%m 

%A %B %a, %Y, %H:%M:%S 

%A 
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%m/%d/%y %1 %p 

%d,%m,%Y %H:%M 

at %K the %dst of %B in %Y 

run job at %I %p, %B %dnd 

%A den %d. %B %Y %H.%M Uhr 

The following are examples of valid input specifications for the above template: 

getdate ("10/1/87 4 PM" ) ; 

getdate ( "Friday" ) ; 

getdate ("Friday September 18, 19 87, 10:30:30"); 

getdate("24,9,1986 10:30"); 

getdate ("at monday the 1st of december in 1986"); 

getdate ("run job at 3 PM, december 2nd"); 

If the LC_TIME category is set to a German locale that includes freitag as a weekday name and 
oktober as a month name, the following would be valid: 

getdate ("freitag den 10. oktober 1986 10.30 Uhr"); 

This example shows how local date and time specification can be denned in the template: 



Invocation 


Line in Template 


getdatefl 1/27/86") 
getdate ( "27 . 11 . 86" ) 
getdate ( "86-11-27 " ) 
getdate ( "Friday 12:00:00") 


%d.%m.%y 
%y-%m-%d 
%A %H:%M:%S 



The following rules apply when converting the input specification into the internal format: 

• If only the weekday is given, today is assumed if the given day is equal to the current day, and 
next week if it is less. 

• If only the month is given, the current month is assumed if the given month is equal to the current 
month, and next year if it is less and no year is given (the first day of the month is assumed if no 
day is given). 

• If no hour, minute and second are given, the current hour, minute and second are assumed. 

• If no date is given, today is assumed if the given hour is greater than the current hour and tomor- 
row is assumed if it is less. 

The following examples help to illustrate the above rules assuming that the current date is Mon Sep 22 
12:19:47 EDT 1986, and the LC_TIME category is set to the default "C" locale. 





Line in 




Input 


Template 


Date 


Mon 


%a 


Mon Sep 22 12:19:47 EDT 1986 


Sun 


%a 


Sun Sep 28 12:19:47 EDT 1986 


Fri 


%SL 


Fri Sep 26 12:19:47 EDT 1986 


September 


%B 


Mon Sep 1 12:19:47 EDT 1986 


January 


%B 


Thu Jan 1 12:19:47 EST 1987 


December 


%B 


Mon Dec 1 12:19:47 EST 1986 


Sep Mon 


%b %a 


Mon Sep 1 12:19:47 EDT 1986 


Jan Fri 


%b %a 


Fri Jan 2 12:19:47 EST 1987 


Dec Mon 


%b %a 


Mon Dec 1 12:19:47 EST 1986 


Jan Wed 1989 


%b %a %Y 


Wed Jan 4 12:19:47 EST 1989 


Fri 9 


%a %K 


Fri Sep 26 09:00:00 EDT 1986 


Feb 10:30 


%b %H'.%S 


Sun Feb 1 10:30:00 EST 1987 


10:30 


%H:%M 


Tue Sep 23 10:30:00 EDT 1986 


13:30 


%H:%M 


Mon Sep 22 13:30:00 EDT 1986 



ERRORS 

Upon failure, getdate () returns NULL and the variable getdate_err is set to indicate the error. 
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The following is a complete list of the getdate_err settings and their interpretation: 

1 the DATEMSK environment variable is null or undefined, 

2 the template file cannot be opened for reading, 

3 failed to get file status information, 

4 the template file is not a regular file, 

5 an error is encountered while reading the template file, 

6 memory allocation failed (not enough memory available), 

7 there is no line in the template that matches the input, 

8 invalid input specification (example: February 31). 

SEE ALSO 

ctime(3C), ctype(3C), setlocale(3C), strftime(3C). 
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NAME 

getdiskbyname() - get disk description by its name 

SYNOPSIS 

ttinclude <disktab.h> 

struct disktab *getdiskbyname (const char *name); 

DESCRIPTION 

getdiskbyname ( ) takes a disk name (such as hp7959B) and returns a pointer to a structure that 
describes its geometry information and the standard disk partition tables. All information is obtained from 
the disktab database file (see disktab(4)). 

The contents of the structure disktab include the following members. Note that there is not necessarily 
any correlation between the placement in this list and the order in the structure. 

drive name */ 
drive type */ 
sector size in bytes */ 

# tracks/cylinder */ 

# sectors /track */ 

# cylinders */ 
revolutions /minute */ 

#sectors in partition */ 
block size in bytes */ 
frag size in bytes */ 

} d_partitions[NSECTIONS]; 
The constant NSECTIONS is defined in <disktab .h>. 

DIAGNOSTICS 

A NULL pointer is returned in case of an error, or if name is not found in the disktab database file. 

AUTHOR 

getdiskbyname ( ) was developed by HP and the University of California, Berkeley. 

SEE ALSO 

disktab(4) 



char 


*d_name; 


/* 


char 


*d_type; 


/* 


int 


d_secsize; 


/* 


int 


d_nt racks; 


/* 


int 


d_nsectors; 


/* 


int 


d_ncyl inder s ; 


/* 


int 


d_rpm; 


/* 


struct 


partition { 






int p_size; 


/* 




short p_bsize; 


/* 




short p_fsize; 


/* 
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NAME 

getenv( ) - return value for environment name 

SYNOPSIS 

ttinclude <stdlib.h> 

char *getenv (const char *name) ; 

DESCRIPTION 

getenv ( ) searches the environment list (see environ(5)) for a string of the form name=value, and returns 
a pointer to the value in the current environment if such a string is present, otherwise a NULL pointer. 
name can be either the desired name, null-terminated, or of the form name=value, in which case 
getenv ( ) uses the portion to the left of the = as the search key. 

WARNINGS 

getenv ( ) returns a pointer to static data which can be overwritten by subsequent calls. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of characters in name as single- and/or multi-byte 
characters. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

STANDARDS CONFORMANCE 

getenv ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 
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NAME 

getfsent(), getfsspec(), getfsfile(), getfstype(), setfsent(), endfsent() - get file system descriptor file entry 

SYNOPSIS 

ttinclude <checklist .h> 

struct checklist *getf sent (void) ; 

struct checklist *getfsspec (const char *spec); 

struct checklist *getfsfile (const char *file); 

struct checklist *getfstype( const char *type); 

int setf sent (void) ; 

int endf sent (void) ; 

Remarks: 

These routines are included only for compatibility with 4.2 BSD. For maximum portability and improved 
functionality, new applications should use the getmntent(3X) library routines. 

DESCRIPTION 

getf sent ( ) , getf sspec ( ) , getf sf lie ( ) , and getf stype ( ) each returns a pointer to an object 
with the following structure containing the broken-out fields of a line in the /etc/checklist file. The 
structure is declared in the <checklist .h> header file: 



struct checklist { 



char 


*fs_spec; 


/* 


char 


*fs bspec; 


/* 


char 


*fs_dir; 


/* 


char 


*fs_type; 


/* 


int 


f s_passno; 


/* 


int 


f s_freq; 


/* 



special file name */ 
block special file name */ 
file sys directory name */ 
type: ro, rw, sw, xx */ 
fsck pass number */ 
backup frequency */ 



}; 



The fields have meanings described in checklist^)- If the block special file name, the file system directory 
name, and the type are not all defined on the associated fine in /etc/checklist, these routines return 
pointers to NULL in the f s_bspec, f s_dir, and f s_type fields. If the pass number or the backup fre- 
quency field are not present on the line, these routines return -1 in the corresponding structure member, 
f s_f req is reserved for future use. 

getf sent ( ) Heads the next fine of the file, opening the file if necessary. 

setf sent ( ) Opens and rewinds the file. 

endf sent ( ) Closes the file. 

getfsspec() Sequentially searches from beginning of file until a matching special file name is 

found, or until EOF is encountered. 

getf sf ile ( ) Sequentially searches from the beginning of the file until a matching file system file 

name is found, or until EOF is encountered, getf stype ( ) Sequentially searches 
from the beginning of the file until a matching file system type field is found, or until 
EOF is encountered. 

DIAGNOSTICS 

A null pointer is returned on EOF, invalid entry, or error. 

WARNINGS 

Since all information is contained in a static area, it must be copied to be saved. 

AUTHOR 

getf sent ( ) was developed by HP and the University of California, Berkeley. 

FILES 

/etc /checklist 

SEE ALSO 

checklist(4). 
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NAME 

getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), fgetgrent() - get group file entry 

SYNOPSIS 

# include <grp.h> 

struct group *getgrent (void) ; 

struct group *getgrgid(gid_t gid) ; 

struct group *getgrnam( const char *name) ; 

void setgrent (void) ; 

void endgrent (void) ; 

struct group * f get grent (FILE *stream) ; 

DESCRIPTION 

getgrent ( ) , get grgid ( ) , and getgrnam ( ) locate an entry in the /etc/group file, and return a 
pointer to an object of type struct group. 

The group structure is defined in <grp . h> and includes the following members: 

char *gr_name; /* the name of the group */ 
char *gr_passwd; /* the encrypted group password */ 
gid_t gr_gid; /* the numerical group id */ 
char **gr_mem; /* null -terminated array of pointers 

to member names */ 

getgrent ( ) When first called, getgrent ( ) returns a pointer to the first group structure in 

the file; thereafter, it returns a pointer to the next group structure in the file. In 
this way, successive calls can be used to search the entire file, getgrent ( ) opens 
the /etc /group file prior to doing its work and leaves the file open afterward; 

setgrent ( ) Has the effect of rewinding this file to allow repeated searches; 

endgrent ( ) Can be called to close the file when processing is complete. 

getgrgid ( ) Searches from the beginning of the file until a numeric group ID matching gid is 

found, and returns a pointer to the particular structure in which it was found. 

getgrnam ( ) Searches from the beginning of the file until a group name matching name is found, 

and returns a pointer to the particular structure in which it was found. 

f getgrent ( ) Returns a pointer to the next group structure in the standard I/O stream stream, 

which should be open for reading, and its contents should match the format of 
/etc /group. 

NETWORKING FEATURES 

NFS 

If an entry beginning with a plus sign (+) or a minus sign (-) is found, these routines try to use the Net- 
work Information Service network database for data. See group (4) for proper syntax and operation. 

RETURN VALUE 

getgrent ( ) , getgrgid ( ) , getgrnam ( ) , and f getgrent ( ) return a NULL pointer if an end-of-file 
or error is encountered on reading. Otherwise, the return value points to an internal static area containing 
a valid group structure. 

WARNINGS 

The above routines use <stdio.h> and the Network Information Service library. This causes them to 
increase the size of programs that do not otherwise use standard I/O and Network Information Service more 
than might ordinarily be expected. 

The value returned by these functions points to a single static area that is overwritten by each call to any of 
the functions. It must be copied if it is to be saved. 

DEPENDENCIES 

NFS: 
FILES 
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/etc/yp/domainname/group .byname 
/etc/yp/domainname/group. bygid 
SEE ALSO: 

ypcat(l). 

FILES 

/etc /group 

SEE ALSO 

getgroups(2), getpwent(3C), stdio(3S), group(4). 

STANDARDS CONFORMANCE 

getgrent ( ) : SVID2, XPG2 
endgrent ( ) : SVID2, XPG2 



f getgrent ( ) : SVID2, XPG2 

getgrgid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SIX.1 

getgrnam ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
setgrent ( ) : SVID2, XPG2 
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NAME 

gethostent(), gethostbyaddr( ), gethostbyname( ), sethostent(), endhostent() - get network host entry 

SYNOPSIS 

ttinclude <sys/socket .h> 
#include <netinet/in.h> 
^include <netdb.h> 

extern int h_errno; 

struct hostent *gethostent (void) ; 

struct hostent *gethostbyname (const char *name); 

struct hostent *gethostbyaddr ( 
const char *addr, 
int len, 
int type ) ; 

int sethostent (int stayopen) ; 

int endhostent (void) ; 

DESCRIPTION 

gethostent ( ) , gethostbyname ( ) , and gethostbyaddr ( ) each return a pointer to a structure of 
type hostent, defined as follows in <netdb . h>: 

struct hostent { 

char *h_name ; 

char **h_aliases; 

int h_addrtype ; 

int h_length; 

char **h_addr_list; 
}; 
#define h_addr h_addr_list [0] 

The members of this structure are: 

h_name The official name of the host. 

h_al iases A null-terminated array of alternate names for the host. 

h_addrtype The type of address being returned; always AF_INET. 

h_length The length, in bytes, of the address. 

h_addr_l i s t A null-terminated array of network addresses for the host. 

h_addr The first address in h_addr_list; this is for compatibility with previous HP-UX 

implementations where a struct hostent contains only one network address per 
host. 

Name Server Operation 

If the local system is configured to use the named name server (see named (1M)): 

gethostent ( ) Always returns a NULL pointer. 

sethostent ( ) , Requests the use of a connected stream socket for queries to the name server 

if the stayopen flag is non-zero. The connection is retained after each call to 
gethostbyname ( ) or gethostbyaddr ( ) . 

endhostent ( ) Closes the stream socket connection. 

gethostbyname ( ) Each retrieves host information from the name server. Names are matched 
gethostbyaddr ( ) without respect to uppercase or lowercase. For example, berkeley.edu, 

Berkeley.EDU , and BERKELEY.EDU all match the entry for 

berkeley.edu. 

NIS Server Operation 

If the local system is not configured to use the name server, but is running ypserv, the Network 
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Information Service server: 
gethostent ( ) 
sethostent ( ) 

endhostent ( ) 

gethostbyname ( ) 
gethostbyaddr ( ) 



Returns the next entry in the NIS database. 

Initializes an internal key for the NIS database. If the stayopen flag is non- 
zero, the internal key is not cleared after calls to endhostent ( ) . 

Clears the internal NIS database key. 

Each retrieves host information from the NIS database. Names are matched 
without respect to uppercase or lowercase. For example, berkeley.edu, 
Berkeley.EDU , and BERKELEY.EDU all match the entry for 
berkeley.edu. 



Non-Server Operation 

If the local system is using neither the local name server nor the Network Information Service server: 



gethostent ( ) 
sethostent ( ) 

endhostent ( ) 
gethostbyname ( ) 



gethostbyaddr ( ) 



Reads the next line of /etc/hosts, opening the file if necessary. 

opens and rewinds the file. If the stayopen flag is non-zero, the host data 
base is not closed after each call to gethostent ( ) (either directly or 
indirectly through one of the other gethost calls). 

Closes the file. 

Sequentially searches from the beginning of the file until a host name 
(among either the official names or the aliases) matching its name parameter 
is found, or until EOF is encountered. Names are matched without respect to 
uppercase or lowercase, as described above in the name server case. 

Sequentially searches from the beginning of the file until an Internet address 
matching its addr parameter is found, or until EOF is encountered. 

In calls to gethostbyaddr ( ) , the parameter addr must point to an Internet address in network order 
(see byteorder(SN)). The parameter len must be the number of bytes in an Internet address; that is, 
s 1 zeof ( s t ruct in_addr ) . The parameter type must be the constant AF_INET. 

RETURN VALUE 

If successful, gethostbyname ( ) , gethostbyaddr ( ) and gethostent ( ) return a pointer to the 
requested hostent struct, gethostbyname ( ) and gethostbyaddr ( ) return NULL if their host or 
addr parameters, respectively, cannot be found in the database. If /etc /hosts is being used, they also 
return NULL if they are unable to open /etc/hosts, gethostbyaddr ( ) also returns NULL if either 
its addr or len parameter is invalid, gethostent ( ) always returns NULL if the name server is being 
used. 

ERRORS 

If the name server is being used and gethostbyname ( ) or gethostbyaddr ( ) returns a NULL 
pointer, the external integer h_errno contains one of the following values: 

No such host is known. 



HOST_NOT_FOUND 
TRY_AGAIN 

NO_RECOVERY 
NO ADDRESS 



This is usually a temporary error. The local server did not receive a response 
from an authoritative server. A retry at some later time may succeed. 

This is a non-recoverable error. 

The requested name is valid but does not have an IP address; this is not a 
temporary error. This means another type of request to the name server will 
result in an answer. 

If the name server is not being used, the value of h_errno may not be meaningful. 

WARNINGS 

All information is contained in a static area so it must be copied if it is to be saved. 

AUTHOR 

gethostent ( ) was developed by the University of California, Berkeley. 

FILES 

/etc/hosts 
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SEE ALSO 

named(lM), ypserv(lM), resolver(3N), ypclnt(3C), hosts(4), ypfiles(4). 
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NAME 

getlogin() - get login name 

SYNOPSIS 

ttinclude <unistd.h> 

char *getlogin(void) ; 

DESCRIPTION 

getlogin ( ) returns a pointer to the login name as found in /etc/utmp. It can be used in conjunction 
with getpwnam ( ) to locate the correct password file entry when the same user ID is shared by several 
login names. 

If getlogin ( ) is called within a process that is not attached to a terminal, it returns a NULL pointer. 
The recommended procedure to obtain the user name associated with the real user ID of the calling process 
is to call getlogin ( ) , and if that fails to call getpwuid ( ) . The function cuserid ( ) can be used to 
obtain the user name associated with the effective user ID of the calling process. 

ERRORS 

getlogin ( ) fails if any of the following is true: 

[EBADF] An invalid file descriptor was obtained. 

[EMFILE] Too many file descriptors are in use by this process. 

[ENFILE] The system file table is full. 

FILES 

/etc/utmp 

SEE ALSO 

getgrent(3C), getpwent(3C), cuserid(3S), utmp(4). 

DIAGNOSTICS 

getlogin ( ) returns the NULL pointer if name is not found. 

WARNINGS 

Return values point to static data whose content is overwritten by each call. 

STANDARDS CONFORMANCE 

getlogin ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
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NAME 



getmntent( ), setmntentQ, addmntentQ, endmntentQ, hasmntopt( ) - get file system descriptor file entry 



SYNOPSIS 

# include 



<mntent .h> 



file *setmntent (const char *path, char *type); 
struct mntent * getmntent (file *stream) ; 
int addmntent (file *stream, struct mntent *mnt); 
char *hasmntopt (struct mntent *mnt, const char *c-pt); 
int endmntent (FILE *stream) ; 

DESCRIPTION 

These routines replace the obsolete get f sent ( ) routines (see getfsent(3X)) for accessing the file system 
description file /etc/checklist. They are also used to access the mounted file system description file 
/etc/mnttab. 

setmntent ( ) Opens a file system description file and returns a file pointer which can then be used 

with getmntent ( ) , addmntent ( ) , or endmntent ( ) . The type argument is the 
same as in/bpere(3C). 

getmntent ( ) Reads the next line from stream and returns a pointer to an object with the following 

structure containing the broken-out fields of a line in the file-system description file, 
<mnt ent . h>. The fields have meanings described in checklist(4). 

struct mntent { 

file system name */ 

file system path prefix */ 

hfs, nfs, swap, or xx */ 

ro, suid, etc. */ 

dump frequency, in days */ 

pass number on parallel fsck */ 

When file system was mounted; */ 

see mnttab(4). */ 

Cnode id from stat of mnt_fsname 

(0 for NFS) */ 

}; 

In the HP Clustered environment, the mnt_cnode field contains the cnode ID associ- 
ated with the file system name named in the mnt_f sname field unless the specified 
file system is of NFS type in which case the mnt_cnode field is set to 0. 
getmntent ( ) obtains the mnt_cnode field for non-NFS type file systems by exe- 
cuting the stat ( ) system call and using the st_rcnode field of the stat structure 
(see stat(2)). 

addmntent ( ) Adds the mntent structure mnt to the end of the open file stream. Note that stream 

must be opened for writing. 

hasmntopt() Scans the mnt_opts field of the mntent structure mnt for a substring that 

matches opt. It returns the address of the substring if a match is found; otherwise. 

endmntent ( ) Closes the file. 



char 


*mnt_f sname ; 


/* 


char 


*mnt_dir; 


/* 


char 


*mnt_type ; 


/* 


char 


*mnt_opts; 


/* 


int 


mnt_freq; 


/* 


int 


mnt_passno; 


/* 


long 


mnt_t ime ; 


/* 
/* 


cnode_ 


_t mnt_cnode; 


/* 
/* 



The following definitions are provided in <anntent .h>: 



#define MNT_CHECKLIST 
#define MNT_MNTTAB 

ttdefine MNTMAXSTR 

#define MNTTYPE_HPS 
ttdefine MNTTYPE_CDFS 
#define MNTTYPE NFS 



"/etc/checklist" 
"/etc/mnttab" 

128 /* Max size string in mntent */ 

"hfs" /* HFS file system */ 
"hfs" /* CD-ROM file system */ 
"nfs" /* Network file system */ 
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ttdefine MNTTYPE_SWAP "swap" 

#deflne MNTTYPE_SWAPFS "swapfs" 

#define MNTTYPE_ IGNORE "ignore" 

#define MNTOPT_DEFAULTS "defaults" 

#define MNTOPT_RO "ro" 

#define MNTOPT_RW "rw" 

ttdefine MNTOPT_SUID "suid" 

#define MNTOPT_NOSUID "nosuid" 

ttdefine MNTOPT_QUOTA "quota" 

#define MNTOPT_NOQUOTA "noquota" 



/* Swap device */ 

/* File system swap */ 

/* Ignore this entry */ 

/* Use all default options */ 

/* Read only */ 

/* Read/write */ 

/* Set uid allowed */ 

/* No set uid allowed */ 

/* Enable disk quotas */ 

/* Disable disk quotas */ 



The following definition is provided for device swap in <mntent . h>: 

ttdefine MNTOPT_END "end" /* swap after end of file system, 

Series 300/400/700 only */ 

The following definitions are provided for file system swap in <mntent . h>: 

#define MNTOPT_MIN "min" /* minimum file system swap */ 



#define MNTOPT_LIM "lim" 
#define MNTOPT_RES "res" 
#define MNTOPT_PRI "pri" 



/* maximum file system swap */ 

/* reserve space for file system */ 

/* file system swap priority */ 



NETWORKING FEATURES 

NFS 

The following definitions are provided in <mntent .h>: 



addmntent ( ) 
endmntent ( ) 



Retry mount in background */ 
Retry mount in foreground */ 
Number of retries allowed */ 
Read buffer size in bytes */ 
Write buffer size in bytes*/ 
Timeout in 1/10 seconds */ 
Number of retransmissions */ 
Server's IP NFS port */ 
Soft mount */ 
Hard mount */ 

Interruptable hard mounts */ 
Uninterruptable hard mounts*/ 
Device file access allowed */ 
No device file access allowed 



to a mntent structure. Some of the fields comprising a mntent structure are optional 
in /etc/checklist and /etc/mnttab. In the supplied structure, such missing 
character pointer fields are set to NULL and missing integer fields are set to -1. 

Returns 1 on error. 

Returns 1. 



#def ine 


MNTOPT_BG 


"bg" 


/ 


#def ine 


MNTOPT_FG 


"fg" 


/ 


#def ine 


MNTOPT_RETRY 


"retry" 


/ 


#def ine 


MNTOPT_RSIZE 


"rsize" 


/ 


#define 


MNTOPT_WSIZE 


"wsize" 


/ 


#def ine 


MNTOPT_TIMEO 


"timeo" 


/ 


ttdef ine 


MNTOPT_RETRANS 


"retrans" 


/ 


#def ine 


MNTOPT_PORT 


"port" 


/ 


#def ine 


MNTOPTJSOFT 


"soft" 


/ 


#def ine 


MNTOPTJHARD 


"hard" 


/ 


#def ine 


MNTOPT_INTR 


"intr" 


/ 


#define 


MNTOPT_NOINTR 


"nointr" 


/ 


#def ine 


MNTOPT DEVS 


"devs" 


/ 


#def ine 


MNTOPT_NODEVS 


"nodevs" 


/ 


RETURN VALUE 








setmntent ( ) 


Returns a null pointer on error. 




getmntent ( ) 


Returns a null po 


inter on error or 


EC 



WARNINGS 

The returned mntent structure points to static information that is overwritten in each call. 

AUTHOR 

addmntent ( ) , endmntent ( ) , getmntent ( ) , hasmntopt ( ) , and setmntent ( ) were developed 
by The University of California, Berkeley, Sun Microsystems, Inc., and HP. 



FILES 



/etc /checklist 
/etc/mnttab 
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SEE ALSO 

checklist(4), getfsent(3X), mnttab(4). 
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NAME 

getnetent(), getnetbyaddr( ), getnetbynameQ, setnetent(), endnetent() - get network entry 

SYNOPSIS 

#include < sys/ socket .h> 
#include <netdb.h> 

struct netent *getnetent (void) ; 

struct netent *getnetbyname (const char *name); 

struct netent *getnetbyaddr (int net, int type); 

int setnetent (int stayopen) ; 

int endnetent (void) ; 

DESCRIPTION 

getnetent ( ) , getnet byname ( ) , and getnetbyaddr ( ) each return a pointer to a structure of type 
netent containing the broken-out fields of a line in the network data base, /etc /networks. 

The members of this structure are: 

n_name The official name of the network. 

n_al iases A null-terminated list of alternate names for the network. 

n_addrtype The type of the network number returned; always AF_INET. 

n_net The network number. 

Functions behave as follows: 

getnetent ( ) Reads the next line of the file, opening the file if necessary. 

setnetent ( ) opens and rewinds the file. If the stayopen flag is non-zero, the network data 

base is not closed after each call to getnetent ( ) (either directly or indirectly 
through one of the other getnet* calls). 

endnetent () Closes the file. 

getnetbyname ( ) Sequentially searches from the beginning of the file until a network name 
(among either the official names or the abases) matching its parameter name is 
found, or until EOF is encountered. 

getnetbyaddr ( ) Sequentially searches from the beginning of the file until a network number 
matching its parameter net is found, or until EOF is encountered. The parame- 
ter net must be in network order. The parameter type must be the constant 
AP_INET. Network numbers are supplied in host order (see byteorder (3N)). 

If the system is running Network Information Service (NFS), getnetbyname ( ) and getnet- 
byaddr ( ) obtain their network information from the NIS server (see ypserv (1M) and ypfiles (4)). 

RETURN VALUE 

getnetent ( ) , getnetbyname ( ) , and getnetbyaddr ( ) return a null pointer (0) on EOF or when 
they are unable to open /etc/networks, getnetbyaddr ( ) also returns a null pointer if its type 
parameter is invalid. 

WARNINGS 

All information is contained in a static area so it must be copied if it is to be saved. 

AUTHOR 

getnetent ( ) was developed by the University of California, Berkeley. 

FILES 

/etc/networks 

SEE ALSO 

ypserv(lM), networks(4), ypfiles(4). 
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NAME 

getnetgrent(), setnetgrent(), endnetgrent(), innetgr() - get network group entry 

SYNOPSIS 

Int innetgr ( 

char *net group, 

char ""machine, 

char *user, 

char * domain 
); 

int setnetgrent (char *netgroup); 
int endnetgrent ( ) ; 

int getnetgrent ( 

char **machinep / 

char **userp, 

char **domainp 
); 

DESCRIPTION 

innetgr ( ) Returns 1 if netgroup contains the machine, user, and domain triple as a member. 

Otherwise, it returns 0. If machine, user, or domain is NULL, innetgr interprets 
NULL to mean, any machine, user, or domain respectively. Refer to netgroup (4) for a 
description of netgroup membership criteria. 

getnetgrent ( ) Returns the next member of a network group. After the call, machinep contains a 
pointer to a string containing the name of the machine part of the network group 
member. Pointers userp and domainp behave in a manner similar to machinep. If 
any of these pointers are returned with a NULL value, they are interpreted as wild 
cards. getnetgrent ( ) allocates space for the names. This space is released 
when an endnetgrent ( ) call is made, getnetgrent ( ) returns 1 if it suc- 
ceeded in obtaining another network group member, if it reached the end of the 
group. 

setnetgrent ( ) Establishes the network group from which getnetgrent ( ) obtains members, and 
also restarts calls to getnetgrent ( ) from the beginning of the list. If the previ- 
ous setnetgrent ( ) call was to a different network group, a endnetgrent ( ) 
call is implied. 

endnetgrent ( ) Frees the space allocated during getnetgrent ( ) calls. 

AUTHOR 

getnetgrent ( ) was developed by Sun Microsystems, Inc. 

FILES 

/etc /netgroup 

SEE ALSO 

netgroup(4). 
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NAME 

getopt(), optarg, optind, opterr - get option letter from argument vector 

SYNOPSIS 

#include <unistd.h> 

int getopt(int argc, char * const argv[], const char *optstring) ; 

extern char *optarg; 

extern int optind, opterr, optopt; 

DESCRIPTION 

get opt ( ) returns the next option letter in argv (starting from argv[ 1 ]) that matches a letter in optstring. 
argc and argv are the argument count and argument array as passed to mainQ. optstring is a string of 
recognized option characters; if a character is followed by a colon, the option takes an argument which may 
or may not be separated from it by white space. 

optind is the index of the next element of the argv[ ] vector to be processed. It is initialized to 1 by the 
system, and getopt ( ) updates it when it finishes with each element of argv[]. 

getopt ( ) returns the next option character from argv that matches a character in optstring, if there is 
one that matches. If the option takes an argument, getopt ( ) sets the variable optarg to point to the 
option-argument as follows: 

• If the option was the last character in the string pointed to by an element of argv, then optarg 
contains the next element of argv, and optind is incremented by 2. If the resulting value of 
optind is greater than or equal to argc, this indicates a missing option argument, and 
getopt ( ) returns an error indication. 

• Otherwise, optarg points to the string following the option character in that element of argv, 
and optind is incremented by 1. 

If, when getopt ( ) is called, argv[ optind ] is NULL, or the string pointed to by argv[ optind ] either does 
not begin with the character - or consists only of the character -, getopt ( ) returns -1 without chang- 
ing optind. If argv[ optind ] points to the string — , getopt ( ) returns -1 after incrementing optind. 

If getopt ( ) encounters an option character that is not contained in optstring, it returns the question- 
mark (?) character. If it detects a missing option argument, it returns the colon character (:) if the first 
character of optstring was a colon, or a question-mark character otherwise. In either case, getopt ( ) sets 
the variable optopt to the option character that caused the error. If the application has not set the variable 
opterr to zero and the first character of optstring is not a colon, getopt ( ) also prints a diagnostic mes- 
sage to standard error. 

The special option — can be used to delimit the end of the options; -1 is returned, and — is skipped. 

RETURN VALUE 

getopt () returns the next option character specified on the command fine. A colon (:) is returned if 
getopt ( ) detects a missing argument and the first character of optstring was a colon ( : ). 

A question-mark (?) is returned if getopt ( ) encounters an option character not in optstring or detects a 
missing argument and the first character of optstring was not a colon ( : ). 

Otherwise, getopt ( ) returns -1 when all command line options have been parsed. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte charac- 
ters. 

International Code Set Support 

Single- and multi-byte character code sets are supported with the exception of multi-byte character file 
names. 

EXAMPLES 

The following code fragment shows to process arguments for a command that can take the mutually 
exclusive options a and b, and the options f and o, both of which require arguments: 
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#lnclude <stdio.h> 

ttinclude <unistd.h> 

main (int argc, char *argv[]) 

{ 

int c; 

int bflg, aflg, errflg; 

extern int optind, opt opt; 



while ( (c = getopt(argc, argv, ":abf:o:")) != -1) 

o<»4 +■ «v i ~ \ r 

on.i.h.w.1. v>-/ \ 

case 'a': 

if (bflg) 

errf lg++; 
else 

aflg++; 
break; 
case 'b': 

if (aflg) 

errf lg++; 
else { 

bf lg++; 
bproc ( ) ; 
} 

break; 
case 'f : 

ifile = optarg; 
break; 
case 'o': 

ofile = optarg; 
break; 
case ':': /* -f or -o without arguments */ 

fprintf (stderr, "Option -%c requires an argument Xn", 

optopt ) ; 
errf lg++; 
break; 
case '?': 

fprintf (stderr, "Unrecognized option: - %c\n", 

optopt ) ; 
errf lg++; 
} 
if (errflg) { 

fprintf (stderr, "usage: . . . "); 
exit (2); 
} 

for ( ; optind < argc; optind++) { 
if (access (argv [optind] , 4)) { 



} 

WARNINGS 

Options can be any ASCII characters except colon ( : ), question mark (?), or null (\ 0). It is impossible to dis- 
tinguish between a ? used as a legal option, and the character that getopt ( ) returns when it 
encounters an invalid option character in the input. 
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SEE ALSO 

getopt(l). 

STANDARDS CONFORMANCE 

getopt ( ) : AES, SVID2, XPG2, XPG3, XPG4, POSIX.2 

optarg: AES, SVID2, XPG2, XPG3, XPG4, P0SIX.2 
opterr: AES, SVID2, XPG2, XPG3, XPG4, P0SDC.2 
optind: AES, SVID2, XPG2, XPG3, XPG4, P0SIX.2 
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NAME 

getpass() - read a password 

SYNOPSIS 

#include <unistd.h> 

char *getpass (const char *prompt); 
DESCRIPTION 



I 



getpass ( ) reads up to a newline or EOF from the file /dev/tty, after prompting on the standard error 
output with the null-terminated string prompt and disabling echoing. A pointer is returned to a null- 
terminated string of at most 8 characters. If /dev/tty cannot be opened, a NULL pointer is returned. 
An interrupt terminates input and sends an interrupt signal to the calling program before returning. 

FILES 

/dev/tty 

SEE ALSO 

crypt(3C). 

WARNING 

The above routine uses <stdio.h>, which causes it to increase, more than might be expected, the size of 
programs not otherwise using standard I/O. 

WARNINGS 

The return value points to static data whose content is overwritten by each call. 

STANDARDS CONFORMANCE 

getpass ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

getprotoentO, getprotobynumber(), getprotobyname( ), setprotoentO, endprotoent() - get protocol entry 

SYNOPSIS 

ttinclude <netdb.h> 

struct protoent *getprotoent (void) ; 

struct protoent *getprotobyname (const char *name); 

struct protoent *getprotobynumber (int proto) ; 

int setprotoent ( int stayopen) ; 

int endprotoent (void) ; 

DESCRIPTION I 

getprotoentO, getprotobyname( ), and getprotobynumber () each return a pointer to a ™ 

structure of type protoent containing the broken-out fields of a line in the network protocol data base, 
/etc/protocols. 

The members of this structure are: 

p_name The official name of the protocol. 

p_aliases A null-terminated list of alternate names for the protocol. 

p proto The protocol number. 

Functions behave as follows: 

getprotoent ( ) Reads the next line of the file, opening the file if necessary. 

setprotoent ( ) Opens and rewinds the file. If the stayopen flag is non-zero, the protocol 

data base is not closed after each call to getprotoent ( ) (either 
directly or indirectly through one of the other get proto* calls). 

endprotoent ( ) Closes the file. 

getprotobyname ( ) Sequentially search from the beginning of the file until a matching proto- 

getprotobynumber ( ) col name (among either the official names or the aliases) or protocol 

number is found, or until EOF is encountered. 

If the system is running Network Information Service (NFS) services, getprotobyname ( ) and 
getprotobynumber ( ) get the host information from the NIS server (see ypserv (1M) and 
ypfiles(4)). 

RETURN VALUE 

getprotoent ( ) , getprotobyname ( ) , and getprotobynumber ( ) return a null pointer (0) on 
EOF or when they are unable to open /etc/protocols. 

WARNINGS 

All information is contained in a static area so it must be copied if it is to be saved. 

AUTHOR 

getprotoent ( ) was developed by the University of California, Berkeley. 

FILES 

/etc /protocols 

SEE ALSO 

ypserv(lM), protocols(4), ypfiles(4). 
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NAME 

getpw() - get name from UID 

SYNOPSIS 

#include <pwd.h> 

int getpw(uid_t uid, char *buf); 

DESCRIPTION 

getpw ( ) searches the password file for a user ID number that equals uid, copies the line of the password 
file in which uid was found into the array pointed to by buf, and returns 0. getpw ( ) returns non-zero if 
uid cannot be found. The fine is null-terminated. 

This routine is included only for compatibility with prior systems, and should not be used; see getpwent(3C) 
for routines to use instead. 

NETWORKING FEATURES 

NFS 

This routine is implemented using getpwuid ( ) (see getpwuid(3C)) and therefore uses the Network 
Information Service network database as described in passwd(4). 

RETURN VALUE 

getpw ( ) returns non-zero on error. 

WARNINGS 

The above routine uses <stdio.h>, which causes it to increase, more than might be expected, the size of 
programs not otherwise using standard I/O. 

AUTHOR 

getpw ( ) was developed by AT&T and HP. 

FILES 

/etc/passwd 

SEE ALSO 

getpwent(3C), passwd(4). 

STANDARDS CONFORMANCE 

getpw():XPG2 
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NAME 

getpwent(), getpwuidQ, getpwnam(), setpwent(), endpwent(), fgetpwent() - get password file entry 

SYNOPSIS 

ttinclude <pwd.h> 

struct passwd * get pwent (void) ; 

struct passwd *getpwuid(uid_t uid) ; 

struct passwd *getpwnam( const char *name); 

void setpwent (void) ; 

void endpwent (void) ; 

struct passwd *f getpwent (PILE *stream) ; 

DESCRIPTION 

getpwent ( ) , getpwuid ( ) , and getpwnam( ) locate an entry in the /etc/passwd file, and return 
a pointer to an object of type struct passwd. 

The passwd structure is denned in <pwd .h> and includes the following members: 

char *pw_name ; 

char *pw_passwd; 

int pw_uid; 

int pw_gid; 

char *pw_age ; 

char *pw_comment ; 

char *pw_gecos ; 

char *pw_dir; 

char *pw_shel 1 ; 

long pw_audid; 

int pw_audf 1 g ; 

The pw_corament field is unused; the others have meanings described mpassivd(4). 

getpwent ( ) When first called, getpwent ( ) returns a pointer to the first passwd structure in 

the file. Thereafter, it returns a pointer to the next pas swd structure in the file. In 
this way, successive calls can be used to search the entire file, getpwent ( ) opens 
the /etc/passwd file prior to doing its work and leaves the file open afterward; 

setpwent ( ) Has the effect of rewinding this file to allow repeated searches; endpwent ( ) Can be 

called to close the file when processing is complete. 

getpwuid ( ) Searches from the beginning of the file until a numeric user ID matching uid is found, 

and returns a pointer to the particular structure in which it was found. 

getpwnam ( ) searches from the beginning of the file until a login name matching name is found, 

and returns a pointer to the particular structure in which it was found. 

f getpwent ( ) returns a pointer to the next passwd structure in the standard I/O stream stream, 

which should be open for reading, and its contents should match the format of 
/etc/passwd. 

SECURITY FEATURES 

If the secure password file (/. secure /etc /pas swd) exists on the system and the calling process has 
permission to access it, the getpwent ( ) routines fill in the encrypted password, audit ID, and audit flag 
from the corresponding entry in that file. 

If the secure password file exists but the caller does not have permission to read it, the encrypted password 
field is set to * and the audit ID and audit flag are set to -1. 

If the secure password file does not exist, the encrypted password in /etc/passwd is returned and the 
audit ID and audit flag are set to -1. 

In situations where it is not necessary to get information from the regular password file, get spwent ( ) is 
significantly faster because it avoids unnecessary searches of the regular password file (see getspwent(3C)), 

HP-UX Release 9.0: August 1992 - 1 - 525 



getpwent(3C) getpwent(3C) 



and does not use the Network Information Service database. 

putpwentO affects only /etc/passwd; the audit ID and audit flag in the password structure are 
ignored, putspwent ( ) must be used to modify /. secure/etc/passwd(see/>afepH>e/i£(3C)). 

NETWORKING FEATURES 

NFS 

If an entry beginning with a plus sign (+) or a minus sign (-) is found, these routines try to use the Network 
Information Service network database for data. See passwd(4) for proper syntax and operation. 

RETURN VALUE 

getpwent ( ) , getpwuid ( ) , getpwnam ( ) , and f getpwent ( ) return a NULL pointer if an end-of-file 
or error is encountered on reading. Otherwise, the return value points to an internal static area containing 
a valid pas swd structure. 

WARNINGS 

The above routines use <stdio.h> and the Network Information Service library, which causes them to 
increase the size of programs, not otherwise using standard I/O and Network Information Service, more 
than might be expected. 

The value returned by these functions points to a single static area that is overwritten by each call to any of 
the functions, so it must be copied if it is to be saved. 

The following fields have numerical limitations as noted: 

• The user ID is an integer value between -2 and UID_MAX inclusive. 

• The group ID is an integer value between and UID_MAX inclusive. 

If either of these values are out of range, the getpwent(3C) functions will reset the associated ID value to 
(UID_MAX+1). 

DEPENDENCIES 

NFS 
Files: 

/etc /yp/domalnname /pas swd . byname 
/etc/yp/domainname/passwd.byuid 

See Also: 

ypcat(l). 

AUTHOR 

getpwent ( ) , getpwuid ( ) , getpwnam ( ) , setpwent ( ) , endpwent ( ) , and f getpwent ( ) were 
developed by AT&T and HP. 

FILES 

/etc/passwd 

SEE ALSO 

ypcat(l), cuserid(3S), getgrent(3C), getlogin(3C), getspwent(3C), stdio(3S), putspwent(3C), passwd(4), 
spasswd(4), limits(5). 

STANDARDS CONFORMANCE 

getpwent ( ) : SVID2, XPG2 
endpwent ( ) : SVID2, XPG2 

f getpwent ( ) : SVID2, XPG2 

getpwnam ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 

getpwuid ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
setpwent ( ) : SVID2, XPG2 
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NAME 

getrpcent(), getrpcbyname(), getrpcbynumber( ) - get rpc entry 

SYNOPSIS 

ttinclude <netdb.h> 

struct rpcent *getrpcent ( ) ; 

struct rpcent *getrpcbyname(char *name); 

struct rpcent *getrpcbynumber (int number); 

int setrpcent (int stayopen); 

int endrpcent ( ) ; 

DESCRIPTION 

getrpcent ( ) , getrpcbyname ( ) , and getrpcbynumber ( ) each return a pointer to an object with 
the following structure containing the broken-out fields of a line in the rpc program number data base, 
/etc/rpc. 

struct rpcent { 

char *r_name; /* name of server for this rpc program */ 

char **r_aliases; /* NULL terminated list of aliases */ 
int r_number; /* rpc program number for this service */ 

}; 

Functions 

getrpcent ( ) Read the next line of the file, opening the file if necessary. 

setrpcent ( ) Open and rewind the file. If the stayopen flag is non-zero, the rpc database is 

not closed after each call to getrpcent ( ) (either directly or indirectly 
through one of the other getrpc*() calls). 

endrpcent ( ) Close the file. 

getrpcbyname ( ) Sequentially search from the beginning of the file until a matching rpc program 

name is found, or until EOF is encountered. 

getrpcbynumber ( ) Sequentially search from the beginning of the file until a matching rpc program 
number is found, or until EOF is encountered. 

RETURN VALUE 

getrpcent (), getrpcbyname (), and getrpcbynumber () return a null pointer (0) on EOF or 
when unable to access the information in /etc/rpc either directly or through a Network Information 
Service database. 

WARNINGS 

All information is contained in a static area so it must be copied if it is to be saved. 

AUTHOR 

getrpcent ( ) was developed by Sun Microsystems, Inc. 

FILES 

/etc/rpc 

SEE ALSO 

rpcinfo(lM), rpc(4). 
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NAME 

getrpcport() - get RPC port number 

SYNOPSIS 

int getrpcport ( 

char *host / 

int prognum, 

int versnum, 

int proto 
);" 

DESCRIPTION 

getrpcport () returns the port number for version versnum of the RPC program prognum running on 
host and using protocol proto. It returns if it cannot contact portmap or if prognum is not registered. If 
prognum is registered but not with version versnum, it returns the port number of the last registered (prog- 
num, proto) pair. 

WARNING 

User applications that call this routine must be linked with /usr/include/librpcsvc . a. For exam- 
ple, 

cc my_source.c -lrpcsvc 

AUTHOR 

getrpcport ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

portmap(lM). 
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NAME 

gets(), fgets() - get a string from a stream 

SYNOPSIS 

ttinclude <stdio.h> 

char *gets(char *s); 

char *f gets (char *s, int n, PILE *stream); 

DESCRIPTION 

gets { ) Reads characters from the standard input stream, stdin, into the array pointed to by s, 

until a new-line character is read or an end-of-file condition is encountered. The new-line 
character is discarded and the string is terminated with a null character. 

f gets ( ) Reads characters from the stream into the array pointed to by s, until n-1 characters are 

read, a new-line character is read and transferred to s, or an end-of-file condition is encoun- 
tered. The string is then terminated with a null character. 

RETURN VALUE 

Upon sucessful completion, f gets ( ) and gets ( ) return s. If the stream is at end-of-file, the end-of-file 
indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for 
the stream is set, errno is set to indicate the error, and a null pointer is returned. 

f error ( ) and f eof ( ) can be used to distinguish between an error condition and an end-of-file condition. 

ERRORS 

f get s ( ) and gets ( ) fail if data needs to be read into the stream's buffer, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data 

was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its 

controlling terminal, and either the process is ignoring or blocking the SIGTTIN sig- 
nal or the process group of the process is orphaned. 

Additional errno values can be set by the underlying read ( ) function (see 
read (2)). 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getc(3S), puts(3S), scanf(3S). 

STANDARDS CONFORMANCE 

gets ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSK.l, ANSI C 

f gets ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
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NAME 

getservent(), getservbyport(), getservbynameO, setservent(), endservent( ) - get service entry 

SYNOPSIS 

#include <netdb.h> 

struct servent *getservent (void) ; 

struct servent *getservbyname ( 
const char ♦name, 
const char *proto) ; 

struct servent *getservbyport (int port, const char *proto) ; 

int setservent (int stayopen) ; 

int endservent (void) ; 

DESCRIPTION 

getservent ( ) , getservbyname ( ) , and getservbyport ( ) each return a pointer to a structure of 
type servent containing the broken-out fields of a line in the network services data base, /etc/services. 

The members of this structure are: 

s_name The official name of the service. 

s_al iases A null-terminated list of alternate names for the service. 

s_port The port number at which the service resides. 

s_prot o The name of the protocol to use when contacting the service. 

Functions behave as follows: 

getservent ( ) Reads the next line of the file, opening the file if necessary. 

setservent ( ) Opens and rewinds the file. If the stayopen flag is non-zero, the services 

data base is not closed after each call to getservent ( ) (either directly 
or indirectly through one of the other getserv* calls). 

endservent ( ) Closes the file. 

getservbyname ( ) Sequentially search from the beginning of the file until a matching service 

getservbyport ( ) name (among either the official names or the aliases) or port number is 

found, or until EOF is encountered. If a non-NULL protocol name is also 
supplied (such as tcp or udp), searches must also match the protocol. 

If the system is running Network Information Service (NFS), get- 
servbynameO gets the service information from the NIS server (see 
ypserv(lM.) and ypfiles(4)). 

RETURN VALUE 

getservent ( ) , getservbyname ( ) , and getservbyport ( ) return a null pointer (0) on EOF or 
when they are unable to open /etc/services. 

WARNINGS 

All information is contained in a static area so it must be copied if it is to be saved. 

AUTHOR 

getservent ( ) was developed by the University of California, Berkeley. 

FILES 

/etc/services 

SEE ALSO 

ypserv(lM), services(4), ypfiles(4). 
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NAME 

getspwent(), getspwuid(), getspwaid(), getspwnam(), setspwentQ, endspwent(), fgetspwent() - get secure 
password file entry 

SYNOPSIS 

# Include <pwd.h> 

struct s_passwd *getspwent (void) ; 

struct s_passwd *getspwuid(uid_t uid) ; 

struct s_passwd *getspwaid(aid_t aid); 

struct s_passwd *getspwnam(const char *name) ; 

void setspwent (void) ; 

void endspwent (void) ; 

struct s_passwd *f get spwent (FILE *stream) ; 

DESCRIPTION 

These privileged routines provide access to the secure password file in a manner similar to the way 
getpwent(SC) routines handle the regular password file, ( /etc/passwd). 

These routines are particularly useful in situations where it is not necessary to get information from the 
regular password file. getspwent(SC) routines run significantly faster than getpwent(3C) routines because 
they avoid unnecessary scanning of the password file and use of Network Information Service. 

get spwent ( ) , getspwuid ( ) , get spwaid ( ) , and get spwnam ( ) each return a pointer to an object. 
The s_passwd structure is written in the / . secure /etc/passwd file, and consists of five fields per 
fine, as follows: 

struct s_passwd { 



char 


*pw_name ; 


/* 


login name */ 


char 


*pw_passwd; 


/* 


encrypted password */ 


char 


*pw_age ; 


/* 


password age */ 


int 


pw_audid; 


/* 


audit ID */ 


int 


pw_audf lg; 


/* 


audit flag l=on, 0=off 



7 
}; 

Since the s_passwd structure is declared in the <pwd . h> header file, it is unnecessary to redeclare it. 

getspwent() When first called, getspwent () returns a pointer to each s_passwd structure in 

/ . secure/etc/passwd in sequence. Subsequent calls can be used to search the 
entire file. 

getspwuid ( ) Searches each entry from the beginning of the file until it finds a numerical user ID 

matching uid. It then returns a pointer to the particular structure in which uid is 
found. getspwaid() Similarly searches for a numerical audit ID matching aid 
and returns a pointer to the particular structure in which aid is found (see spasswd(4) 
for details on this field). 

ge t spwnam ( ) Searches from the beginning of the file until a login name matching name is found. 

Returns a pointer to the particular structure in which name is found. 

setspwent ( ) Resets the file pointer to the beginning of the / . secure/etc/passwd file to allow 

repeated searches. 

endspwent Can be called to close the secure password file when processing is complete. 

f getspwent Returns a pointer to the next s_passwd structure in the stream stream, which 

matches the format of / . secure/etc/passwd. 

RETURN VALUE 

getspwent ( ) returns a NULL pointer if any of these routines encounter an end-of-file or error while 
searching, or if the effective user ID of the calling process is not zero. 

WARNINGS 

The above routines use <stdio.h>, which causes them to increase the size of programs by more than 
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might otherwise be expected. 

Since all information is contained in a static area, it must be copied to be saved. 

AUTHOR 

get spwent ( ) was developed by HP. 

PILES 

/ . secure /etc /pas swd 

SEE ALSO 

ypcat(l), getgrent(3C), getlogin(3C), getpwent(3C), putspwent(3C), passwd(4), spasswd(4). 
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NAME 

getsubopt( ) - parse suboptions from a string. 

SYNOPSIS 

#include <unistd.h> 

int get subopt (char **optionp, char *tokens[], char **valuep) ; 

DESCRIPTION 

getsubopt() parses suboptions in a flag argument that were initially parsed by getopt ( ) (see 
getopt(3C)). These suboptions are separated by commas, and may consist of either a single token, or a 
token-value pair separated by an equal sign. Because commas delimit suboptions in the option string, they 
are not allowed to be part of the suboption or the value of a suboption. Similarly, because the equal sign 
separates a token from its value, a token must not contain an equals sign. An example command that uses 
this syntax is mount, mount allows parameters to be specified with the - 
switch as follows: 

mount -o rw / hard,bg,wsize=1024 speed: /usr /usr 

In this example there are four suboptions: rw, hard, bg, and wsize, the last of which has an associated 
value of 1024. 

get subopt ( ) takes the address of a pointer to the option string, a vector of possible tokens, and the 
address of a value string pointer. It returns the index of the token that matched the suboption in the input 
string or -1 if there was no match. If the option string at *optionp contains only one suboption, get su- 
bopt ( ) updates *optionp to point to the null at the end of the string, otherwise it isolates the suboption 
by replacing the comma separator with a null, and updates *optionp to point to the start of the next subop- 
tion. If the suboption has an associated value, get subopt ( ) updates *valuep to point to the value's first 
character. Otherwise it sets *valuep to NULL. 

The token vector is organized as a series of pointers to NULL-terminated strings. The end of the token vec- 
tor is identified by NULL. 

When getsubopt() returns, if *valuep is not NULL then the suboption processed included a value. The 
calling program can use this information to determine if the presence or lack of a value for this suboption is 
an error. 

Additionally, when get subopt ( ) fails to match the suboption with the tokens in the tokens array, the 
calling program should decide if this is an error, or if the unrecognized option should be passed on to 
another program. 

EXAMPLES 

The following code fragment shows how options can be processed to the mount command by using get- 
subopt ( ) . 

char *myopts[] = { 
#define READONLY 

"ro", 
#define READWRITE 1 

"rw", 
#define WRITESIZE 2 

"wsize", 
#define READSIZE 3 

"rsize", 

NULL}; 

main (int argc, char **argv) 
{ 

int sc, c, errflag; 

char *options, *value; 

extern char *optarg; 

extern int optind; 
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while ((c = getopt(argc, argv, "abf:o:")) != EOF) 
switch (c) { 
case 'a': /* process 'a' option */ 

break; 
case 'b': /* process 'b' option */ 

break; 

Case J- • 

of lie = optarg; 
break; 
case '?': 

errf lag++; 
break; 

options = optarg; 

while (*options 1= '\0') { 

switch ( get subopt (& opt ions, myopts, &value) ) { 
case READONLY: /* process ro option */ 

break; 
case READWRITE: /* process rw option */ 

break; 
case WRITESIZE: /* process wsize option */ 
if (value == NULL) { 
error_no_arg ( ) ; 
errf lag++; 
} 
else 

write_size = atoi (value); 
break; 
case READSIZE: /* process rsize option */ 
if (value == NULL) { 
error_no_arg ( ) ; 
errf lag++; 
} 
else 

read_size = atoi (value); 
break; 
default: 

/* process unknown token */ 
error_bad_token (value) ; 
errf lag++; 
break; 
} 
} 

break; 
} 
} 
if (errflg) { 

f print f (stderr, "usage: . . . "); 
exit (2); 
} 
for ( ; optind < argc; optind++) { 

/* process remaining arguments */ 



} 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte 

534 - 2 - HP-UX Release 9.0: August 1992 



getsubopt(3C) getsubopt(3C) 



characters. 

International Code Set Support 

Single- and multi-byte character code sets are supported with the exception of multi-byte-character file 
names. 

SEE ALSO 

getopt(3C). 

STANDARDS CONFORMANCE 

getsubopt ( ) : SVID3 
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NAME 

gettimer - get value of a per-process timer 

SYNOPSIS 

#include <sys/tlmers ,h> 

int gettimer (timer_t timerid, struct itimerspec *value); 

DESCRIPTION 

gettimer () returns an itimerspec structure value to the value argument. The it_value member of the 
structure represents the amount of time in the current interval before the timer expires for the timer 
specified in timerid, or zero if the timer is disabled. The itjnterval member has the value last set by rel- 
timer() (see reltimer(3C)). The members of value are subject to the resolution of the timer (see 
mktimer(SC)). 

The behavior of this function is undefined if value is NULL. 

RETURN VALUE 

Upon successful completion, gettimer () returns zero; otherwise, it returns -1 and set er mo to indi- 
cate the error. 

ERRORS 

gettimer () fails if any of the following conditions are encountered: 

[EINVAL] timerid does not correspond to an ID returned by mkt imer ( ) . 
[EIO] An error occurred while accessing the clock device. 

SEE ALSO 

reltimer(3C), mktimer(3C), <sys/timers.h>. 

STANDARDS CONFORMANCE 

get t imer ():AES 
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NAME 

getusershellO, setusershell(), endusershell() - get legal user shells 

SYNOPSIS 

#include <unistd.h> 

char *getusershell (void) ; 
void setusershell(void) ; 
void enduser shell (void) ; 

DESCRIPTION 

getusershellO Returns a pointer to the first legal user shell as denned in the file 

/etc/shells (see shells(4)). If /etc/shells does not exist or is not read- 
able, getusershellO returns the following standard system shells: 

/bin/sh 

/bin/rsh 

/bin/ksh 

/bin/rksh 

/bin/csh 

/bin/pam 

/usr/bin/keysh 

/bin/posix/sh 

as if they were contained in /etc/ shells. The file is left open so that the next call returns the next 
shell. A null pointer (0) is returned on EOF or error. 

setusershellO 
Rewinds the file. 

enduser shell ( ) 
Closes the file. 

WARNINGS 

All information is contained in a static area and therefore must be copied if it is to be saved. 

AUTHOR 

getusershell ( ) was developed by HP and the University of California, Berkeley. 

FILES 

/etc/shells 

SEE ALSO 

shells(4). 
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NAME 

getutent(), getutid(), getutline(), pututline(), _pututline( ), setutent(), endutent(), utmpname( ) - access 
utmp file entry 

SYNOPSIS 

#include <utmp.h> 

struct utmp * get utent (void) ; 

struct utmp *getutid (struct utmp *id); 

struct utmp *getutline (struct utmp *line); 

struct utmp *_putut line (const struct utmp *utmp) ; 

void putut line (const struct utmp *utmp) ; 

void setutent (void) ; 

void endutent (void) ; 

void utmpname (const char *file); 

DESCRIPTION 

getutent ( ) , getutid ( ) . 
type: 



and getutline() each return a pointer to a structure of the following 



struct utmp { 

char ut_user[8]; 
char ut__id[4] ; 
char ut_line[12]; 
pid_t ut_pid; 
short ut_type; 
struct exit_status { 

short e_termination; 

short e_exit ; 

} ut_exit; 



}; 



/* 
/* 
/* 
/* 
/* 

/* 
/* 
/* 
/* 

unsigned short ut_reservedl; 
time_t ut_time; /* 

char ut_host[16]; /* 
unsigned long ut_addr; /* 



User login name */ 

/etc/inittab id (usually line #) */ 

device name (console, lnxx) */ 

process id */ 

type of entry */ 

Process termination status */ 
Process exit status */ 
The exit status of a process */ 
marked as DEAD_PROCESS. */ 

/* Reserved for future use */ 
time entry was made */ 

host name, if remote; NOT SUPPORTED */ 
Internet addr of host, if remote */ 



getutent ( ) Reads in the next entry from a utmp-like file. If the file is not already open, getu- 

tent ( ) opens it. If it reaches the end of the file, getutent ( ) fails. 

getut id ( ) Searches forward from the current point in the utmp file until it finds an entry with a 

ut_type matching id->ut_type if the type specified is RUN_LVL, BOOT_TIME, 
OLD_TIME, or NEW_TIME. If the type specified in id is INIT_PROCESS, 
LOGINJPROCESS, USER.PROCESS, orDEAD_PROCESS, getut id () returns 
a pointer to the first entry whose type is one of these four, and whose ut_id field 
matches id->ut_id. If end-of-file is reached without a match, getutid ( ) fails. 

getut line ( ) Searches forward from the current point in the utmp file until it finds an entry of type 

LOGIN_PROCESS or USER_PROCESS that also has a ut_llne string matching 
the line->ut_line string. If end-of-file is reached without a match, getut line () 
fails. 

pututlineO Writes out the supplied utmp structure into the utmp file, putut line () uses 

getutid ( ) to search forward for the proper location if it is not already there. It is 
normally expected that the application program has already searched for the proper 
entry by using one of the getut ( ) routines before calling putut line ( ) . If the 
search as already been made, pututlineO does not repeat it. If pututline () 
does not find a matching slot for the new entry, it adds a new entry to the end of the 
file. 
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_pututline ( ) Performs the same actions as pututline ( ) , except that it returns a value useful 
for error checking. 

setutent ( ) Resets the input stream to the beginning of the file. This should be done before each 

search for a new entry if it is desired that the entire file be examined. 

endutent ( ) Closes the currently open file. 

utmpname ( ) Allows the user to change the name of the file being examined from /etc/utmp to 

any other file. The other file is usually /etc/wtmp. If the file does not exist, its 
absence is not discovered until the first subsequent attempt to reference the file, 
utmpname ( ) does not open the file — it merely closes the old file if it is currently 
open, and saves the new file name. 

The most current entry is saved in a static structure. Multiple accesses require that the structure be copied 
before further accesses are made. During each call to either getutid( ) or getutline ( ) , the static 
structure is examined before performing more I/O. If the contents of the static structure match what the 
routine is searching for, no additional searching is done. Therefore, if using getutline ( ) to search for 
multiple occurrences, it is necessary to zero out the static structure after each success; otherwise getut - 
1 ine ( ) simply returns the same pointer over and over again. There is one exception to the rule about 
removing the structure before a new read: The implicit read done by pututline ( ) (if it finds that it is 
not already at the correct place in the file) does not alter the contents of the static structure returned by 
getutent ( ) , getut id ( ) , or getutline ( ) if the user has just modified those contents and passed 
the pointer back to pututline ( ) . 

RETURN VALUE 

These functions return a NULL pointer upon failure to read (whether for permissions or having reached 
end-of-file), or upon failure to write. They also return a NULL pointer if the size of the file is not an integral 
multiple of sizeof (struct utmp) . 

_pututline ( ) behaves the same as pututline ( ) , except that it returns a pointer to a static location 
containing the most current utmp entry if the _pututline() call succeeds. The contents of this struc- 
ture is identical to the contents of the supplied utmp structure if successful. If _pututline ( ) fails, it 
returns a NULL pointer. 

WARNINGS 

Some vendors' versions of getutent ( ) erase the utmp file if the file exists but is not an integral multiple 
of sizeof (struct utmp) . Given the possiblity of user error in providing a name to utmpname (such 
as giving improper arguments to who(l)), HP-UX does not do this, but instead returns an error indication. 

FILES 

/etc/utmp 
/etc/wtmp 

SEE ALSO 

ttyslot(3C), utmp(4). 

STANDARDS CONFORMANCE 

endutent ( ) : SVID2, XPG2 

getutent ( ) : SVID2, XPG2 
getut id ( ) : SVID2, XPG2 
getut 1 ine ( ) : SVID2, XPG2 
pututline ( ) : SVID2, XPG2 
setutent ( ) : SVID2, XPG2 
utmpname ( ) : SVID2, XPG2 
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NAME 

getwc(), getwchar(), fgetwcO - get a wide character from a stream file 

SYNOPSIS 

# include <wchar.h> 

wint_t getwc(PILE *stream) ; 
wint_t getwchar(void) ; 
wint_t f getwc (FILE *stream) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. 
They parallel the 8 bit character I/O functions defined in getc(3S) . 

DESCRIPTION 

getwc ( ) Returns the next character from the named input stream, converts that to the correspond- 

ing wide character and moves the file pointer ahead one character in stream. 
getwchar() is defined as getwc (stdin). getwc () and getwchar() are defined 
both as macros and as functions. 

f getwc ( ) Behaves like getwc ( ) , but is a function rather than a macro. 

Definitions for these functions, the types wint_t , wchar_t and the value WEOP are provided in header 
file<wchar.h>. 

RETURN VALUE 

Upon successful completion, getwc (), getwchar(), and fgetwcO return the next wide character 
read from stream (stdin for getwchar ( ) ) converted to a type wint_t. If the stream is at end-of-file, 
the end-of-file indicator for the stream is set and WEOP is returned. If a read error occurs, the error indica- 
tor for the stream is set, errno is set to indicate the error, and WEOP is returned. 

f error ( ) and f eof ( ) can be used to distinguish between an error condition and an end-of-file condi- 
tion. 

ERRORS 

getwc ( ) , getwchar ( ) , and f getwc ( ) fail if data needs to be read into the stream's buffer, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data 

was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its 

controlling terminal, and either the process is ignoring or blocking the SIGTTIN sig- 
nal or the process group of the process is orphaned. 

[EILSEQ] The data obtained from the input stream does not form a valid wide character. 

Additional errno values may be set by the underlying read ( ) function (see read(2)). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

WARNINGS 

getwc () and getwchar () are implemented both as library functions and macros. The macro versions, 
which are used by default, are defined in <wchar.h>. To obtain the library function, either use a 
#undef to remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in 
parenthesis or use the function address. The following example illustrates each of these methods : 

#include <wchar.h> 
#undef getwc 
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main() 
{ 



wint_t ( *get_wchar ( ) ) ( ) ; 
return_val=getwc (c, f d) ; 
re turn_val= (getwc) (c,fdl); 
<ret wo bar = ^stwcliar - 



}; 



If the value returned by getwc ( ) , getwchar ( ) , or f getwc ( ) is stored into a type wchar_t variable 
then compared against the constant WEOP, the comparison may never succeed because extension of a 
wchar_t to a wint_t is machine-dependent. 

The macro version of getwc ( ) incorrectly treats a stream argument with side effects. In particular, 
getwc (*f + +) does not work sensibly. The function version of getwc ( ) or f getwc ( ) should be used 
instead. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). 

STANDARDS CONFORMANCE 

getwc ( ) : XPG4 

f getwc ( ) : XPG4 
getwchar ( ) : XPG4 
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NAME 

glob(), globfreeO - file name generation function 

SYNOPSIS 

#include <glob.h> 

int glob( 

const char *pattern / 

int flags, 

int (*errfunc) (const char *, int), 

glob_t *pglob 
); 

void globf ree(glob_t *pglob) ; 

DESCRIPTION 

glob ( ) is a pathname generator, pattern is a pointer to a pathname pattern to be expanded. If pattern 
contains any of the special characters *, ?, or [, pattern is matched against all accessible pathnames. In 
order to have access to a pathname, glob ( ) requires: 

• Search permission on every component of a path except the last. 

• Read permission on each directory of any filename component of pattern that contains any of the 
above special characters. 

glob() stores the number of matched pathnames in pglob -> gl_pathc and a pointer to a sorted list of 
pathnames in pglob ->gl_pathv. The first pointer after the last pathname is a NULL pointer. 

It is the caller's responsibility to allocate space for the structure pointed to by pglob. glob( ) allocates 
other space as needed, including the memory pointed to by gl_pathv. globf ree ( ) frees any space asso- 
ciated with pglob from a previous call to glob ( ) . 

The flags argument is used to control the behavior of glob ( ) . The value of flags is the bit-wise inclusive 
OR of the following constants defined in <glob . h>: 

GLOB_NOESCAPE Disable backslash escaping. 

GLOB_ERR Causes glob ( ) to return when it first encounters a directory that it cannot 

open or read. Ordinarily, glob ( ) continues to find matches. 

GLOB_MARK Each pathname that matches pattern and is a directory has a / appended. 

GLOB_NOSORT Ordinarily, glob( ) sorts the matching pathnames according to the currently 

active collation sequence as defined by the LC_COLLATE category. When this 
flag is used, the order of pathnames returned is unspecified. 

GLOB_NOCHECK If pattern does not match any pathname, glob( ) returns a list consisting of 
only pattern, and the number of matched pathnames is 1. 

GLOB_DOOPFS Make use of pglob ->gl_offs. If this flag is set, pglob ->gl_offs is used to specify 

how many NULL pointers to add to the beginning of pglob ->gl_pathv. In other 
words, pglob ~>gl_pathv points to pglob ->gl_offs NULL pointers, followed by 
pglob ->gl_pathc pathname pointers, followed by a NULL pointer. 

GLOB_APPEND Append pathnames generated to the ones from a previous call to glob ( ) . 

If GLOB_APPEND is specified in flags, the following rules apply: 

• If the application set GLOB_DOOPPS in the first call to glob ( ) , then it also sets it in all 
subsequent calls to glob ( ) , as long as the same glob_t structure is used for appending. 

• If the application did not set GLOB_DOOFFS in the first call to glob ( ) , then it does not set 
it in any subsequent calls to glob ( ) , as long as the same glob_t structure is used for 
appending. 

• If GLOB_DOOPPS is set, the value of pglob ->gl_offs must not be modified between calls to 
glob(). 

• After the second call, pglob ->gl_pathv points to a list containing the following: 
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• Zero or more NULLs, as specified by GLOB_DOOPS and pglob ->gl_offs. 

• Pointers to the pathnames that were in the pglob ->gl_pathv list before the call, in 
the same order as before. 

• Pointers to the new pathnames generated by the second call, in the specified order. 

• The count returned in pglob ->gl_pathc is the sum of the number of pathnames matched in the previ- 
ous and current calls to glob ( ) . 

• The application does not modify pglob ->gl_pathc or pglob ->gl_pathv between calls to glob ( ) . 

If, during the search, a directory is encountered that cannot be opened or read and errfunc is not NULL, 
glob ( ) calls (*errfunc)Q with two arguments: 

• A pointer to the path that failed. 

• The value of errno from the failure. 

If errfunc is called and returns non-zero, or if the GLOB_ERR flag is set in flags, glob() stops the scan 
and returns GLOB_ABORTED after setting gl_pathc and gl_pathv in pglob to reflect the paths 
already scanned. If GLOB_ERR is not set and either errfunc is NULL or (*errfunc)() returns zero, the error 
is ignored. 

Pattern Matching Notation 

The form of the patterns is the Pattern Matching Notation as qualified for Filename Expansion (see 
regexp(S)) with the following exceptions: 

• Tilde (~) expansion is not performed. 

• Variable expansion is not performed. 

If a filename component ends with a plus sign (+) (indicating a context-dependent file), the plus sign must 
be explicitly matched by a plus sign in the pattern; it cannot be matched by either the asterisk or question 
mark special characters, or by bracket expressions. 

EXTERNAL INFLUENCES 
Locale 

The LC_COLLATE category determines the collating sequence used in compiling and executing regular 
expressions, and also the order of the returned paths if GLOB_NOSORT is not selected. 

The LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and 
which characters are matched by character class expressions in regular expressions. 

International Code Set Support 

Single- and multi-bye character code sets are supported. 

RETURN VALUE 

If glob() terminates due to an error, it returns one of the following constants (defined in <glob.h>); 
otherwise, it returns zero. 

GLOB_NOSPACE An attempt to allocate memory failed. 

GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*errfunc)() returned 
non-zero. 

GLOB_NOMATCH The pattern does not match any existing pathname, and GLOB_NOCHECK was 
not set in flags. 

In any case, the argument pglob ->gl_pathc returns the number of matched pathnames and the argument 
pglob ->gl_pathv contains a pointer to a null-terminated list of matched and sorted pathnames. 

However, iipglob ->gl_pathc is zero, the content of pglob ->gl_pathv is undefined. 

If the pattern argument passed to glob ( ) is badly constructed, glob ( ) returns zero and sets 
gl_pathc to zero unless GLOB_NOCHECK was set, in which case pattern is returned and gl_pathc is 
set to 1. 

WARNINGS 

GLOB_APPEND must not be set in an initial call to glob ( ) . 
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AUTHOR 

glob() and globf ree ( ) were developed by HP. 

SEE ALSO 

ed(l), grep(l), sh(l), fnmatch(3C), malloc(3C), malloc(3X), regexp(5). 

STANDARDS CONFORMANCE 

globf ree ( ) : XPG4, P0SIX.2 
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NAME 

gpio_get_status - return status lines of GPIO card 

SYNOPSIS 

#include <dvio.h> 

int gpio_get_status(int eid) ; 

DESCRIPTION 

gpio_get_status ( ) reads the status register of the GPIO interface associated with the device file 
identified by eid. eid is an entity identifier of an open GPIO device file obtained from an open ( ) , dup ( ) , 
f exit i ( ) , or creat ( ) caii (see open{2), dup{2), fcnti{2), or creai(2)). The current state of each status line 
on the interface card is mapped to the value returned, with STS0 mapped to the least significant bit. Only 
x least-significant bits are used, where x is the number of status fines available on the hardware interface 
being used. 

DEPENDENCIES 
Series 300/400 

For the HP 98622 A, x is 2. 

Series 800 

FortheHP27114A,xis2. 

For the HP27114B, x is 6. 
For the HP 2865 1A, x is 5. 

RETURN VALUE 

gpio_get_status ( ) returns the value of the status register of the GPIO interface associated with eid, 
and -1 if an error was encountered. 

ERRORS 

gpio_get_status ( ) fails if any of the following conditions are encountered and sets errno accord- 
ingly: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a GPIO device file. 
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NAME 

gpio_set_ctl - set control lines on GPIO card 

SYNOPSIS 

ttinclude <dvio.h> 

int gpio_set_ctl (int eid, int value); 

DESCRIPTION 

gpio_set_ct 1 ( ) sets the control register of a GPIO interface, eid is an entity identifier of an open GPIO 
device file obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call (see open(2\ dup{2), fcntl(2), 
and creat{2)). value is the value to be written into the control register of the GPIO interface associated with 
eid. 

value is mapped onto the control lines on the interface card, with the least significant bit mapped to CTLO. 
Only the x least significant bits are used, where x is the number of control fines available on the hardware 
interface being used. 

DEPENDENCIES 
Series 300/400 

For the HP 98622 A, x is 2. 

Series 800 

For the HP27114A, x is 3. 

FortheHP27114B,xis6. 
FortheHP28651A,*is5. 

RETURN VALUE 

gpio_set_ctl ( ) returns if successful and -1 if an error was encountered. 

ERRORS 

gpio_set_ct 1 ( ) fails if any of the following conditions are encountered, and sets errno accordingly: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a GPIO device file. 
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NAME 

hpib_abort() - stop activity on specified HP-IB bus 

SYNOPSIS 

#include <dvio.h> 

int hpib_abort (int eid) ; 

DESCRIPTION 

hpib_abort ( ) terminates activity on the addressed HP-IB bus by pulsing the IFC line, eid is an entity 
identifier of an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) 
call. 

hpib_abort ( ) also sets the REN line and clears the ATN fine. The status of the SRQ line is not affected. 
The interface must be the system controller of the bus. 

RETURN VALUE 

hpib_abort ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_abort () fails under the following circumstances, and sets errno (see errno(2)) to the value in 
square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the specified interface is not the system controller (see DEPENDENCIES below). 

[ETIMEDOUT] a timeout occurred. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock(3l)). 

DEPENDENCIES 
Series 300/400: 

The HP 98625A/B and HP 25560A HP-IB interfaces do not clear the ATN line. EIO is returned if a timeout 
occurs. 

Series 800: 

If the interface is not currently the system controller, hpib_abort ( ) sets errno to [EACCES] instead of 
to [EIO]. 

AUTHOR 

hpib_abort ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2). 
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NAME 

hpib_address_ctl() - set the HP-IB bus address for an interface 

SYNOPSIS 

ttinclude <dvio.h> 

int hpib_address_ctl(int eid, int ba); 

DESCRIPTION 

hpib_address_ctl ( ) sets the HP-IB bus address of the interface associated with eid to ba. eid is an 
entity identifier of an open HP-IB raw bus device file obtained from an open( ) , dup ( ) , f cntl ( ) , or 
creat ( ) call, ba is an integer and must be in the range of [0-30]. 

The new bus address remains in effect until a reboot, an io_reset ( ) call, or another 
hpib_address_ctl () call occurs. When a reboot ( ) or io_reset() call occurs, the HP-IB bus 
address reverts to its powerup value. 

RETURN VALUE 

hpib_address_ctl ( ) returns (zero) if successful or -1 if an error was encountered. 

ERRORS 

hpib_address_ctl () fails under the following circumstances and sets errno (see errno{2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] a timeout occurred. 

[EINTR] the request was interrupted by a signal. 

[EINVAL] ba is not in the range of 0-30. 

AUTHOR 

hpib_address_ctl ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), io_reset(3I). 
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NAME 

hpib_atn_ctl() - control the Attention line on HP-IB 

SYNOPSIS 

#include <dvio.h> 

int hpib_atn_ctl (int eid, lnt flag); 

DESCRIPTION 

hpib_atn_ctl () enables/disables the Attention (ATN) line, depending on the value of flag, eid is an 
entity identifier of an open HP-IB raw bus device file obtained from an open( ), dup ( ) , f cntl ( ) , or 
creat ( ) call, flag is an integer which, if non-zero, enables the ATN line, and otherwise disables it. 

RETURN VALUE 

hpib_atn_ctl () returns (zero) if successful or -1 if an error was encountered. 

ERRORS 

hpib_atn_ctl ( ) fails under the following circumstances, and sets errno (see errno(2)) to the value in 
square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not the active controller or a timeout occurred. 

AUTHOR 

hpib_atn_ctl ( ) was developed by HP. 
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NAME 

hpib_bus_status( ) - return status of HP-IB interface 

SYNOPSIS 

ftinclude <dvio.h> 

int hpib_bus_status (int eid, int status); 

DESCRIPTION 

hpib_bus_status ( ) obtains status information about an HP-IB channel, eid is an entity identifier of 
an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call, status 
is an integer determining what status information is returned for a particular call. The values defined for 
status and their associated meanings are: 

REMOTE_STATUS Is the channel currently in remote state? 

SRQ_STATUS What is the current state of the SRQ line? 

NDAC_STATUS What is the current state of the NDAC line? 

SYS_CONT_STATUS Is the channel currently system controller? 

ACT_CONT_STATUS Is the channel currently active controller? 

TALKER_STATUS Is the channel currently addressed as talker? 

LI STENER_STATUS Is the channel currently addressed as listener? 

CURRENT_BUS_ADDRES S 

What is the channel's bus address? 

The remote-state status is not defined when the interface is the active controller, although reading 
remote-state status in such a situation is not an error. Determining the status of the NDAC fine is not 
available on all machines, and its use is therefore discouraged to ensure compatibility among various sys- 
tems. Machines that do not support sensing the NDAC fine return an error. 

RETURN VALUE 

The value returned by hpib_bus_status ( ) depends upon the value of status. If status is 
CURRENT_BUS_ADDRESS, the return value is either the HP-IB bus address or -1 if an error occurred. If 
status is any of the other values, the return value is if the condition is false (the fine is clear), 1 if the con- 
dition is true (the fine is set), or -1 if an error occurred. 

ERRORS 

hpib_bus_status ( ) fails under the following conditions, and sets errno (see errao(2)) to the value in 
square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EINVAL] status is not one of the values specified above. 

DEPENDENCIES 
Series 300/400: 

The status of signal lines being driven by the interface is undefined, although reading them in such a situa- 
tion is not an error. Non-active controllers cannot sense the SRQ line. Active listeners cannot sense the 
NDAC line. 

The HP 98625A/B HP-IB interface cannot determine the current state of the NDAC line. Attempts to read this 
fine fail and set errno (see errno(2)) to EINVAL. 

AUTHOR 

hpib_bus_status ( ) was developed by HP. 
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NAME 

hpib_card_ppoll_resp() - control response to parallel poll on HP-IB 

SYNOPSIS 

#include <dvio.h> 

int hpib_card_ppoll_resp(int eid, int flag); 

DESCRIPTION 

hpib_card_ppoll_resp() enables or disables an interface for parallel polls. It also controls the 
sense, and determines the line on which the response is sent. This provides a means for the interface to 
ignore or respond to a parallel poll according to whether it is enabled to respond. 

eid is an entity identifier of an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , 
f cnt 1 ( ) , or creat ( ) call, flag is an integer having one of the following bit patterns: 

Bit Pattern Meaning 

10000 Disable parallel poll response. 

0SPPP Enable parallel poll response, where 

S = sense of the response, and 

PPP = 3-bit binary number specifying the line on which the response is sent where 
the octal values through 7 correspond to lines DIOl through DI08. 

RETURN VALUE 

hpib card ppoll reap ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_card_ppoll_resp ( ) fails under the following circumstances, and sets errno (see errao(2)) to 
the value in square brackets: 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock (31)). 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EINVAL] the device cannot respond on the line number specified by flag. 

[ETIMEDOUT] a timeout occurred. 

DEPENDENCIES 
Series 300/400: 

The HP 98625A/B and HP 25560A HP-IB interfaces support only enabling and disabling the parallel poll 
response (bit 4 of flag). The sense and response line number are not programmable on this card. 

EIO is returned if a timeout occurs. 

Series 800: 

Since the sense and response line number are not programmable on the HP27110B HP-IB interface, the 
equivalent parallel poll configuration commands are sent over the HP-IB to the interface. Therefore, this 
function fails if the interface is not active controller. 

AUTHOR 

hpib_card_ppoll_resp ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), hpib_ppoll(3l), hpib_ppoll_resp_ctl(3I). 
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NAME 

hpib_eoi_ctl() - control EOI mode for HP-IB file 

SYNOPSIS 

ftinclude <dvio.h> 

int hpib_eoi_ctl(int eid, int flag); 

DESCRIPTION 

hpib_eoi_ct 1 ( ) enables you to turn EOI mode on or off. eid is an entity identifier of an open HP-IB raw 
device file obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call, flag is an integer which, if 
non-zero, enables EOI mode, and otherwise disables it. 

EOI mode causes the last byte of all subsequent write operations to be written out with the EOI line 
asserted, signifying the end of the data transmission. By default, EOI mode is disabled when the device file 
is opened. 

Entity identifiers for the same device file obtained by separate open ( ) requests have their own EOI modes 
associated with them. Entity identifiers for the same device file obtained by dup ( ) or inherited by a 
fork ( ) request share the same EOI mode. In the latter case, if one process enables EOI mode, then EOI 
mode is in effect for all such entity identifiers. 

RETURN VALUE 

hpib_eoi_ctl ( ) returns a (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_eoi_ctl ( ) fails under any of the following circumstances and sets errno (see errao(2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB device file. 

DEPENDENCIES 
Series 800: 

EOI mode is enabled when the device file is first opened. 

AUTHOR 

hpib_eoi_ctl ( ) was developed by HP. 
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NAME 

hpib_io( ) - perform I/O with an HP-IB channel from buffers 

SYNOPSIS 

#include <dvio.h> 

int hpib_io(int eid, struct iodetail *iovec, size_t iolen) ; 

DESCRIPTION 

hpib_io ( ) performs and controls read and/or write operations on the specified HP-IB bus. eid is an entity 
identifier of an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) 
call. 

Parameters are as follows: 

iovec Pointer to an array of structures of the form: 

struct iodetail { 

char mode ; 

char terminator; 

int count ; 

char *buf ; 
}; 

The iodetail structure is defined in the include file <dvio . h>. 

iolen 
Specifies the number of structures in iovec . 

iodetail Structure 

Elements in the i ode t a i 1 structure are : 

mode Describes what is to be done during I/O on the buffer pointed to by buf. mode is con- 

structed by OR-ing flags from the following list: 

One and only one of the following two flags must be specified: 

HPIBREAD Perform a read of the HP-IB bus, placing data into the accom- 
panying buffer. 

HPIBWRITE 

Perform a write to the HP-IB bus, using data from the accom- 
panying buffer. 

The following flags can be used in most combinations (not all combinations are valid), or not at all: 

HP I BATN Data is written with ATN enabled. 

HPIBEOI Data written is terminated with EOI (this flag is ignored when HP IBATN is enabled). 

HPIBCHAR Data read is terminated with the character given in the terminator element of the iode- 
tail structure. 

terminator 
Describes the termination character, if any, that should be checked for on input, count is an integer 
specifying the maximum number of bytes to be transferred. 

A read operation terminates when either count is matched, an EOI is detected, or the designated termina- 
tor is detected (if HPIBCHAR is set in mode). 

A write operation terminates when count is matched, and the final byte is sent with EOI asserted (if HPI- 
BEOI is set in mode). 

If HPIBATN is set in mode, write operations occur with ATN enabled. Setting HPIBATN for a read 
operation is ignored and has no effect. 

The members of the iovec array are accessed in order. 

RETURN VALUE 

If all transactions are successful, hpib_io ( ) returns a zero and updates the count element in each 
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structure in the iovec array to reflect the actual number of bytes read or written. 

If an error is encountered during a transaction defined by an element of iovec, hpib_io ( ) returns 
without completing any transactions that might follow. In particular, if an error occurs, hpib_io ( ) 
returns a -1, and the count element of the transaction that caused the error is set to -1. 

ERRORS 

hpib_io( ) fails under any of the following circumstances, and sets errno (see errreo(2)) to the value 
indicated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[ETIMEDOUT] a timeout occurred. 

[EIO] eid is not the active controller. 

DEPENDENCIES 
Series 300/400: 

EIO is returned if a timeout occurs. 

Series 800: 

If the interface is not currently the active controller, hpib_io ( ) sets errno to [EACCES] instead of to 
[EIO]. 

AUTHOR 

hpib_io ( ) was developed by HP. 



554 - 2 - HP-UX Release 9.0: August 1992 



hpib_parity_ctl ( 31 ) Series 300, 400 Only hpib_par ity_ctl ( 31 ) 



NAME 

hpib_parity_ctl() - enable/disable odd parity on ATN commands 

SYNOPSIS 

ttinclude <dvio.h> 

int hpib_parity_ctl(int eid, int flag); 

DESCRIPTION 

hpib_parity_ctl ( ) enables/disables the sending of odd parity for ATN command sequences depending 
upon the value of flag, eid is an entity identifier of an open HP-IB raw bus device file obtained from an 
open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, flag is an integer which, if non-zero, enables odd parity 
and otherwise disables it. 

Entity identifiers for the same device file obtained by separate open ( ) requests have their own parity 
flags associated with them. Entity identifiers for the same device file obtained by dup ( ) or inherited by a 
fork ( ) request share the same parity flag. In the latter case, if one process changes the parity flag, the 
new parity flag is in effect for all such entity identifiers. 

RETURN VALUE 

hplb parity ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hplb_parlty_ctl ( ) fails under the following circumstances, and sets errno (see errno{2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

AUTHOR 

hpib_parity_ctl ( ) was developed by HP. 
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NAME 

hpib_pass_ctl() - change active controllers on HP-IB 

SYNOPSIS 

#include <dvio.h> 

int hpib_pass_ctl(int eid, lnt ba) ; 

DESCRIPTION 

hpib_pass_ct 1 ( ) passes control of a bus to an inactive controller on that bus. The inactive controller 
becomes the active controller of that bus. eid is an entity identifier of an open HP-IB raw bus device file 
obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, ba is the bus address of the intended 
device. 

Not all devices can accept control. Pass control passes only active control of the bus; it cannot pass system 
control of the bus. The specified interface must be the current active controller but need not be the system 
controller. The pass control operation does not suspend program execution if the inactive controller does 
not take active control of the bus. However, the interface is no longer active controller. 

RETURN VALUE 

hplb pass ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_pass_ctl ( ) fails under any of the following circumstances, and sets errno (see errao(2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not the active controller. 

[ETIMEDOUT] a timeout occurred. 

[EINVAL] ba is not a valid HP-IB bus address. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock (31)). 

DEPENDENCIES 
Series 300/400: 

EIO is returned if a timeout occurs. 

Series 800: 

If the interface is not currently the active controller, hpib_pass_ctl ( ) sets errno to [EACCES] 
instead of to [EIO]. 

AUTHOR 

hpib_pass_ctl ( ) was developed by HP. 
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NAME 

hpib_ppoll() - conduct parallel poll on HP-IB bus 

SYNOPSIS 

#include <dvio.h> 

int hpib_ppol(int eid) ; 

DESCRIPTION 

hpib__ppoll ( ) conducts a parallel poll on an HP-IB bus. eid is an entity identifier of an open HP-IB raw 
bus device file obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call. 

Devices enabled to respond that are in need of service can then assert the appropriate DIO line. This 
enables the controller to determine which devices, if any, need service at a given time. hpib_ppoll ( ) 
delays for 25 microseconds before returning with the response. The interface must be the active controller 
to conduct a parallel poll. 

RETURN VALUE 

hpib_ppoll ( ) returns an integer value whose least significant byte corresponds to the byte formed by 
the eight data input/output (DIO) lines. Devices enabled to respond to a parallel poll do so on the appropri- 
ate DIO line. DIO line 1 corresponds to the least significant bit in the response byte; line 8 to the most 
significant bit. A return value of -1 indicates that an error occurred. 

ERRORS 

hpib_ppoll ( ) fails under the following situations, and sets errno (see errno(2)) to the value in square 
brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not current the active controller. 

AUTHOR 

hpib_ppoll ( ) was developed by the Hewlett-Packard Company. 
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NAME 

hpib_ppoll_resp_ctl() - define interface parallel poll response 

SYNOPSIS 

#include <dvio.h> 

int hpib_ppoll_resp_ctl(int eid, int response); 

DESCRIPTION 

hpib_ppoll_resp_ctl ( ) defines a response to be sent when an active controller performs a parallel 
poll on an HP-IB interface, eid is an entity identifier of an open HP-IB raw bus device file, obtained from an 
open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call. 

The value of response indicates whether this computer does or does not need service. A non-zero response 
value indicates that sendee is required. This statement only sets up a potential response; no actual 
response is generated when the statement is executed. The sense of the response and the line number to 
respond on are set by hpib_card_ppoll_resp ( ) (see hpib_cardjjpoll_resp(SI)) or by the active con- 
troller. 

RETURN VALUE 

hplb ppoll resp ct 1 ( ) returns if the response is successfully set, or -1 if an error has occured. 

ERRORS 

hplb_ppoll_resp_ctl ( ) fails under the following situations, and sets errno (see errno(2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a raw HP-IB device file. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock(3I)). 

AUTHOR 

hpib_ppoll_resp_ctl ( ) was developed by HP. 

SEE ALSO 

hpib_ppoll(3l), hpib_card_ppoll_resp(3l) 
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NAME 

hpib_ren_ctl() - control the Remote Enable line on HP-IB 

SYNOPSIS 

ttinclude <dvio.h> 

int hpib_ren_ctl(int eid, int flag); 

DESCRIPTION 

hpib_ren_ct 1 ( ) enables/disables the Remote Enable (REN) line depending upon the value of flag, eid is 
an entity identifier of an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or 
creat ( ) call, flag is an integer which, if non-zero, enables the REN line, and otherwise disables it. 

hpib_ren_ctl () can be used in conjunction with hpib_send_cmnd( ) to place devices into the 
remote state or local state. The REN line is normally enabled at all times, and is in this state at power-up. 
Only the system controller can enable or disable the REN line. 

RETURN VALUE I 

hpib_ren_ctl ( ) returns (zero) if successful, or -1 if an error was encountered. H 

ERRORS 

hpib_ren_ctl ( ) fails under the following circumstances, and sets errno (see errno(2)) to the value in 
square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not the system controller. 

AUTHOR 

hpib_ren_ctl ( ) was developed by HP. 
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NAME 

hpib_rqst_srvce() - allow interface to enable SRQ line on HP-IB 

SYNOPSIS 

#include <dvio.h> 

int hpib_rqst_srvce(int eld, int cv); 

DESCRIPTION 

hpib_rqst_srvce ( ) specifies a response byte to be sent by the interface when it is serially polled by 
the active controller, eid is an entity identifier of an open HP-IB raw bus device file obtained from an 
open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, cv is an integer control value representation of the desired 
response byte. 

hpib_rqst_srvce ( ) optionally enables the SRQ fine depending upon the response byte. If bit 6 of the 
response byte is set, the SRQ fine is enabled. It remains enabled until the active controller conducts a serial 
poll or until the computer executes the request function with bit 6 cleared. However, the SRQ line is not 
enabled as long as the interface is active controller. If bit 6 is set, the interface remembers its response 
byte, and enables the SRQ fine when control is passed to another device on the bus. 

The response byte is structured as follows: 

Bit Meaning 

SPOLL bit (least significant bit of response byte) 

1 SPOLL bit 

2 SPOLL bit 

3 SPOLL bit 

4 SPOLL bit 

5 SPOLL bit 

6 SRQ line 

7 SPOLL bit (most significant bit of response byte) 

RETURN VALUE 

hpib_rqst_srvce ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_rqst_srvce() fails under the following circumstances, and sets errno (see errno{2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[ETIMEDOUT] a timeout occurred. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock(3l)). 

DEPENDENCIES 
Series 300/400: 

The HP98625A/B and HP25560A HP-IB interface cards allow only bit 6 to be set. All other bits are cleared. 

EIO is returned if a timeout occurs. 

Series 800: 

The HP27110B HP-IB interface card allows only bit 6 to be set. All other bits are cleared. 

AUTHOR 

hpib_rqst_srvce ( ) was developed by HP. 
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NAME 

hpib_send_cmnd( ) - send command bytes over HP-IB 

SYNOPSIS 

#include <dvio.h> 

int hpib_send_cmnd(int eid, const char *ca, int length); 

DESCRIPTION 

hpib_send_cmnd() sends specified arbitrary bytes of information on the HP-IB with the ATN line 
asserted, providing a means to configure and control the bus. eid is an entity identifier of an open HP-IB 
raw bus device file obtained from an open(), dup(), fcntl(), or creat{) call, ca is a character 
pointer to a string of bytes to be written to the HP-IB bus as commands, length is an integer specifying the 
number of bytes in the string pointed to by ca. 

The interface must currently be the active controller in order to send commands over the bus. 

Note that for all HP-IB interfaces, both built-in and plug-in, the most significant bit of each byte is overwrit- I 

ten with a parity bit. All commands are written with odd parity. ■ 

RETURN VALUE 

hpib_send_cmnd ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

hpib_send_cmnd ( ) fails under the following circumstances, and sets errno (see errno (2)) to the value 
in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not currently the active controller. 

[ETIMEDOUT] a timeout occurred. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see iojock (31)). 

[EINVAL] The value specified for length is invalid, either less than or equal to or greater than 

MAX_HPIB_COMMANDS as defined in <dvio . h>. 

DEPENDENCIES 
Series 300/400: 

EIO is returned if a timeout occurs. 

Series 800: 

If the interface is not currently the active controller, hpib_send_cmnd() sets errno to [EACCES] 
instead of [EIO]. 

AUTHOR 

hpib_send_cmnd ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), hpib_parity_ctl(3l). 
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NAME 

hpib_spoll( ) - conduct a serial poll on HP-IB bus 

SYNOPSIS 

ttinclude <dvio.h> 

int hpib_spoll (int eid, int ba); 

DESCRIPTION 

hpib_spoll ( ) conducts a serial poll of the specified device, eid is an entity identifier of an open HP-IB 
raw bus device file obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, ba is the bus address 
of the intended device. 

hplb_spoll ( ) Polls a single device for its response byte. The information stored in the response byte is 
device specific with the exception of bit 6. If bit 6 of the response byte is set, the addressed device has 
asserted the SRQ line, and is requesting service (note that the least significant bit of the response byte is bit 
0). 

Not all devices respond to the serial poll function. Consult device documentation. Specifying a device that 
does not support serial polling may cause a timeout error or suspend your program indefinitely. The inter- 
face cannot serial poll itself. The interface must be the active controller. 

RETURN VALUE 

If hpib_spoll ( ) is successful, the device response byte is returned in the least significant byte of the 
return value. Otherwise, -1 is returned, indicating an error. 

ERRORS 

hpib_spoll () fails under the following circumstances, and sets errno (see errao(2)) to the value in 
square brackets: 

[EBAD] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[EIO] the interface is not the active controller. 

[ETIMEDOUT] the device polled did not respond before timeout. 

[EINVAL] ba is the address of the polling interface itself. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock(3l)). 

DEPENDENCIES 
Series 300/400: 

EIO is returned if a timeout occurs. 

Series 800: 

If the interface is not currently the active controller, hpib_spoll ( ) sets errno to [EACCES] instead of 
to [EIO]. 

AUTHOR 

hpib_spoll ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), hpib_rqst_srvce(3l). 
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NAME 

hpib_status_wait( ) - wait until the requested status condition becomes true 

SYNOPSIS 

# include <dvio.h> 

int hpib_status_wait (int eid, int status); ttinclude <dvio.h> 

DESCRIPTION 

hpib_status_wait () waits until a specific condition has occurred before returning, eid is an entity 
identifier of an open HP-IB raw bus device file obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) 
call, status is an integer specifying what information is returned. The possible values for status and their 
associated meanings are: 

WAIT_POR_SRQ Wait until SRQ line is enabled. 

WAIT_FOR_CONTROL Wait until this channel is active controller. 

WAIT_POR_TALKER Wait until this channel is addressed as talker. 

WAIT_POR_LISTENER Wait until this channel is addressed as listener. 

The wait is subject to the current timeout in effect. If a timeout occurs before the desired condition occurs, 
the function returns with an error. 

RETURN VALUE 

hpib_status_wait () returns zero when the condition requested becomes true. A value of -1 is 
returned if an error occurs. A -1 is also returned if a timeout occurs before the desired condition becomes 
true. 

ERRORS 

hpib_status_wait ( ) fails under the following circumstances, and sets errno (see errno(2)) to the 
value in square brackets: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB raw bus device file. 

[ETIMEDOUT] a timeout occurred. 

[EINVAL] status contains an invalid value. 

[EACCES] the interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock(3I)). 

DEPENDENCIES 
Series 300/400: 

EIO is returned if a timeout occurs. 

The following error is also defined: 

[EIO] the device is active controller and status specifies WAIT_FOR_TALKER or 

WAIT_FOR_LISTENER. 

AUTHOR 

hpib_status_wait ( ) was developed by HP. 
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NAME 

hpib_wait_on_ppoll( ) - wait until a particular parallel poll value occurs 

SYNOPSIS 

#include <dvio.h> 

int hpib_wait_on_ppoll (int eid, lnt mask, int sense) ; 

DESCRIPTION 

hpib_wait_on_ppoll () waits for a parallel poll response to occur on one or more lines, eid is an 
entity identifier of an open HP-IB raw bus device file. 

The mask argument specifies on which fines the parallel poll response is expected. The value of mask is 
treated as an eight-bit binary number where the least significant bit corresponds to fine DIOl; the most 
significant bit to DIOS. For example, if you want to wait for a response on lines DI02 and DI06, the 
corresponding binary number is 00010010, so a hexadecimal value of 12 should be passed as the mask 
argument. 

The sense argument specifies what response is expected on the selected lines. The value of sense is con- 
structed in the same way as mask ; eight bits for eight lines. If a bit in sense is set, the function returns 
when the line corresponding to that bit is cleared. If a bit in sense is clear, the function returns when the 
corresponding line is set. Using the previous example, if mask is 0x12 and sense is 00000010 (0x02 hexade- 
cimal), the function returns when line DI05 is set, or when line DI02 is clear. 

RETURN VALUE 

hplb_wait_on__ppoll ( ) returns a value of-1 if an error or timeout condition occurs. Upon successful 
completion, the function returns the response byte XOR-ed with the sense value and AND-ed with the mask. 

ERRORS 

hpib_wait_on_ppoll ( ) fails and sets errno to indicate the error if any of the following is true: 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see io_lock (31)). 

[EBADF] The eid argument is not a valid open entity identifier. 

[ENOTTY] The eid argument does not refer to an HP-IB raw bus device file. 

[EINVAL] An invalid mask is received. 

[EIO] The interface is not currently the active controller. 

[EIO] A timeout occurred (Series 300/400 only). 

[ETIMEDOUTJ A timeout occurred (Series 800 only). 

DEPENDENCIES 
Series 300/400: 

[EIO] is returned if a timeout occurs. 

Series 800: 

If the interface is not currently the active controller, hpib_wait_on_ppoll ( ) sets errno to [EACCES] 
instead of to [EIO]. 

AUTHOR 

hpib_wait_on_ppoll ( ) was developed by HP. 
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NAME 

HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONG- 
DIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD - 3000-mode packed-decimal library 

SYNOPSIS 

# include <hppac.h> 

void HPPACADDD ( 

unsigned char *operand2, 

int op2digs, 

unsigned char ^operandi, 

int opldigs, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACCMPD ( 

unsigned char ^operandi, 

int opldigs, 

unsigned char *operand2, 

int op2digs, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACCVAD ( 

unsigned char *target, 

int targetdigs, 

unsigned char *source, 

int sourcedigs, 

enum HPPAC_CC *compcode, 

int *pac status 
); 

void HPPACCVBD ( 

unsigned char *target, 

int targetdigs, 

unsigned short * source, 

int sourcewords, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACCVDA ( 

unsigned char *target, 

int targetdigs, 

unsigned char *source, 

int sign_control, 

enum HPPAC_CC *compcode, 

int *pac status 
); 

void HPPACCVDB ( 

unsigned short *target, 

unsigned char *source, 

int sourcedigs, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACDIVD ( 

unsigned char *operand2, 
int op2digs, 
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unsigned char *operandl, 
int opldigs, 

enum HPPAC_CC *compcode, 
int *pacstatus 
); 

void HPPACLONGDIVD ( 

unsigned char *operand2, 

int op2digs, 

unsigned char *operandl, 

int opldigs, 

enum HPPAC_CC *compcode, 

int *pacstatus 
) ; 

void HPPACMPYD( 

unsigned char *operand2, 

int op2dlgs, 

unsigned char *operandl, 

int opldigs, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACNSLD( 

unsigned char *operand2, 

int op2digs, 

unsigned char *operandl, 

int opldigs, 

int *shift_amt, 

enum HPPAC_CC *compcode, 

int *pacstatus # 

int *carry 
); 

void HPPACSLD( 

unsigned char *operand2, 

int op2digs, 

unsigned char *operandl, 

int opldigs, 

int shift_amt, 

enum HPPAC_CC *compcode, 

int *pacstatus, 

int *carry 
); 

void HPPACSRD( 

unsigned char *operand2, 

int op2digs, 

unsigned char *operandl, 

int opldigs, 

int shift_amt, 

enum HPPAC_CC *compcode, 

int *pacstatus 
); 

void HPPACSUBD( 

unsigned char *operand2, 

int op2digs, 

unsigned char *operandl, 

int opldigs, 

enum HPPAC_CC *compcode, 



566 



-2- 



HP-UX Release 9.0: August 1992 



hppac(3X) Series 800 Only hppac(3X) 



int *pacstatus 
); 

DESCRIPTION 

This set of calls invokes the library functions for emulating 3000-mode (MPE V/E) packed-decimal opera- 
tions. These functions are in library libel which is searched when the option -lcl is used with cc( 1) or 
ta(l). 

HPPACADDDO 

Performs packed-decimal addition. 

HPPACCMPDO 

Compares two packed-decimal numbers. 

HPPACCVADO 

Converts an ASCII representation to packed-decimal. 

HPPACCVBDO 

Converts a binary representation to packed-decimal. 

HPPACCVDAO 

Converts a packed-decimal number to ASCII. 

HPPACCVDB ( ) 

Converts a packed-decimal number to binary. 

HPPACDIVDO 

Performs packed-decimal division. 

HPPACLONGDIVDO 

Performs packed-decimal division (alternate routine). 

HPPACMPYD ( ) 

Performs packed-decimal multiplication. 

HPPACNSLDO 

Performs a packed-decimal normalizing left shift. 

HPPACSLD ( ) Performs a packed-decimal left shift. 

HPPACSRD ( ) Performs a packed-decimal right shift. 

HPPACSUBD ( ) 

Performs packed-decimal subtraction. 

For all operations, the value returned in the variable to which the compcode argument points is one of the 
following values of type enum HPPAC_CC: 

HPPAC_CCG Result > or operandi > operand2 

HPPAC_CCL Result < or operandi < operand2 

HPPAC_CCE Result == or operandi == operand2 

For all operations, the value returned in the variable to which the pacstatus argument points is one of the 
following values of type enum HPPAC_STATUS. Their meanings are intended to be obvious: 

HPPAC_NO_ERROR 

HPPAC_DECIMAL_OVERFLOW 

HPPAC_INVALID_ASCI I_DIGIT 

HPPAC_INVALID_PACKED_DECIMAL_DIGIT 

HPPAC_INVALI D_SOURCE_WORD_COUNT 

HPPAC_INVALID_DECIMAL_OPERAND_LENGTH 

HPPAC_DECIMAL_DIVIDE_BY_ZERO 

AUTHOR 

The HPPAC library was developed by HP. 
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SEE ALSO 

Compiler Library /XL Reference Manual 
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NAME 

hsearchO, hcreate(), hdestroyO - manage hash search tables 

SYNOPSIS 

ttinclude <search.h> 

ENTRY *hsearch (ENTRY item, ACTION action); 
int he reate (unsigned nel); 
void hdes troy (void) ; 

DESCRIPTION 

hsearch ( ) is a hash-table search routine generalized from Knuth (6.4) Algorithm D. It returns a pointer 
into a hash table indicating the location at which an entry can be found, item is a structure of type ENTRY 
(denned in the <search .h> header file) containing two pointers: points to the comparison key, and points 
to any other data to be associated with that key. (Pointers to types other than character should be cast to 
pointer-to-character.) action is a member of an enumeration type ACTION indicating the disposition of the 
entry if it cannot be found in the table. ENTER indicates that the item should be inserted in the table at 
an appropriate point. FIND indicates that no entry should be made. Unsuccessful resolution is indicated 
by the return of a NULL pointer. 

hcreate ( ) allocates sufficient space for the table, and must be called before hsearch ( ) is used, nel is 
an estimate of the maximum number of entries that the table will contain. This number can be adjusted 
upward by the algorithm in order to obtain certain mathematically favorable circumstances. 

hdes troy ( ) destroys the search table, and can be followed by another call to hcreate () . 

EXAMPLE 

The following example reads in strings followed by two numbers and stores them in a hash table, discard- 
ing duplicates. It then reads in strings and finds the matching entry in the hash table and prints it out. 

#include <stdio.h> 
#include <search.h> 

struct info { /* this is the info stored in the table */ 

int age, room; /* other than the key. */ 
}; 
#define NUMJEMPL 5000 /* # of elements in search table */ 



main( ) 
{ 



/* space to store strings */ 
char string_space[NUM_EMPL*20] ; 

/* space to store employee info */ 
struct info inf o_space [NDM_EMPL] ; 

/* next avail space in string_space */ 
char *str_ptr = string_space; 

/* next avail space in info_space */ 
struct info *info_ptr = info_space; 
ENTRY item, *found_item, *hsearch( ); 
/* name to look for in table */ 

char name_to_f ind[30] ; 
int i = 0; 

/* create table */ 

(void) hcreate (NUM_EMPL) ; 

while (scanf ("%s%d%d" , str_ptr, &lnf o_ptr->age, 

& inf o_ptr-> room) != EOF && i++ < NUM_EMPL) { 
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/* put info in structure, and structure in item */ 

item. key = str_ptr; 

item. data = (char *)info_ptr; 

str_ptr += strlen(str_ptr) +1; 

info_ptr++; 

/* put item into table */ 
(void) hsearch(item, ENTER); 
} 

/* access table */ 

item. key = name_to_f ind; 

while (scanf("%s", item. key) 1= EOF) { 

if ((found_item = hsearch(item, FIND)) != NULL) { 

/* if item is in the table */ 

( void) printf ("found %a, age = %&, room = %d\n" , 
found_item->key, 

((struct info *)found_item->data)->age, 
((struct info *)found_item->data)->room) ; 
} else { 
(void) printf ("no such employee %s\n", 
name_to_f ind) ; 
} 



} 



RETURN VALUE 

hsearch( ) returns a NULL pointer if either the action is FIND and the item could not be found or the 
action is ENTER and the table is full. 

he re ate ( ) returns zero if it cannot allocate sufficient space for the table. 

WARNINGS 

hsearchO and hcreate() use malloc() to allocate space (see malloc (3 C)). 

Only one hash search table can be active at any given time. 

SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C). 

STANDARDS CONFORMANCE 

hsearch ( ) : AES, SVID2, XPG2, XPG3, XPG4 

hcreate ( ) : AES, SVID2, XPG2, XPG3, XPG4 
hdestroy ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

hypot(), cabs() - Euclidean distance function, complex absolute value 

SYNOPSIS 

ftinclude <math.h> 

double hypot (double x, double y) ; 
double cabs (struct {double x, y; } z); 

DESCRIPTION 

hypot ( ) and cabs() return sqrt (x*x +y*y), taking precautions against unwarranted overflows. 

hypot () and cabs() return +INFINITY when a: or y is INFINITY. 

ERRORS 
/lib/libm.a 

When the correct value would overflow, hypot ( ) and cabs ( ) return HUGE_VAL and set errno to 
ERANGE. 

hypot ( ) and cabs() return NaN and set errno toEDOM when at ory isNaN. 

These error-handhng procedures can be changed with the matherr ( ) function (see matherr(SM.)). 

/lib/libM.a 

No error messages are printed on the standard error output. 

When the correct value would overflow, hypot ( ) and cabs ( ) return HUGE_VAL and set errno to 
ERANGE. 

hypot ( ) and cabs ( ) return NaN and set errno to EDOM when x or y is NaN. 

These error-handhng procedures can be changed by using the _matherr ( ) function (see matherr(3M)). 
Note that _matherr ( ) is provided in order to assist in migrating programs from llbm.a to llbM.a 
and is not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

isinf(3M), isnan(3M), matherr(3M). 

STANDARDS CONFORMANCE 

hypot ( ) in libm.a: AES, SVID2, XPG2, XPG3 
hypot ( ) in libM.a: AES, XPG3, XPG4 
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NAME 

iconvsize, iconvopen, iconvclose, iconvlock, ICONV, ICONVl, ICONV2 - code set conversion routines 

SYNOPSIS 

#include <iconv.h> 

int iconvsize (const char *tocode, const char *fromcode); 

iconvd iconvopen (const char *tocode, const char *fromcode, 
unsigned char *table, int dl, int d2); 

int iconvclose (iconvd cd) ; 

int iconvlock (iconvd cd, int direction, int lock, const char *s); 

int ICONV (iconvd cd, const unsigned char **inchar, size_t 

♦inbytesleft, unsigned char **outchar, size_t *outbyteslef t) ; 

int ICONVl (iconvd cd, unsigned char *to, 

unsigned char *from, size_t buf len) ; 

int IC0NV2 (iconvd cd, unsigned char *to, 

unsigned char *from, size_t buf len) ; 

Remarks 

For conformance to standards currently under development, the interfaces described in this manual entry 
may be replaced with others in a future release. To make migration easier, application writers should take 
care to isolate use of these functions. 



DESCRIPTION 

iconvsize ( ) 



iconvopen () 



iconvclose () 



Find the size of a table if one is needed to convert characters from the code set specified 
by the fromcode argument to the code set specified by the tocode argument. If a conver- 
sion table is needed and the table exists, the size of the table in bytes is returned. If a 
table is needed and the table does not exist, -1 is returned. If a conversion table is not 
needed, is returned. 

Perform all initializations that have to be done to convert characters from the code set 
specified by the fromcode argument to the code set specified by the tocode argument and 
return a conversion descriptor of type iconvd that identifies the conversion. Up to 
MAX_CD conversions can be open simultaneously. See iconv(l) for HP-supplied from- 
code and tocode names and their corresponding code sets. For conversions that require 
a table, the table argument is a pointer to the start of the conversion table. It is the 
caller's responsibility to allocate sufficient memory for the table which is given by 
iconvsize ( ) . For conversions that do not require a table, the table argument must 
be a NULL pointer. iconvsize () can be used to determine whether a table is 
needed. For multi-byte code sets, a "converted from" character is mapped to a default 
character (dl or d2) if it does not have an equivalent in the "converted to" code set. 
Currently supported multi-byte code sets can have character lengths of one or two bytes. 
If a one-byte character is unmapped, the default one-byte character dl is used. Simi- 
larly, if a two-byte character is unmapped, the default two-byte character d2 is used. 
Default characters are used since different multi-byte code sets typically do not have the 
same number of characters which makes a one-to-one mapping difficult. Also, unused 
sections in multi-byte code sets are usually reserved for future use. A different 
approach is taken with single-byte code sets. For single-byte code sets, it is assumed 
that the translation table forces a one-to-one mapping between the "from" and "to" char- 
acters. No default characters are used with single-byte code sets. This one-to-one map- 
ping guarantees that the conversion is reversible. For example, if the output of a 
ROMAN8-to-ISO 8859/1 conversion is converted back to ROMAN8, the result of this double 
conversion is the same as the original data. 

Close the conversion descriptor cd freeing it up for a subsequent iconvopen ( ) . It is 
the caller's responsibility to de-allocate any table associated with the cd conversion 
descriptor. 

If needed, code set lock-shift information for the conversion identified by cd can be ini- 
tialized by iconvlock ( ) . If direction is 0, strings is used as a lock-shift sequence for 
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the "converted from" or input data. If direction is 1, string s is used as a lock-shift 
sequence for the "converted to" or output data. Currently, three lock-shift sequences can 
be used in a conversion: lock-shift 0, lock-shift 1 and lock-shift 2. These are identified 
by the lock parameter values 0, 1 and 2. iconvlock( ) also resets any state infor- 
mation to the initial shift state. 

ICONV( ) Fetch a character in the "converted from" code set from an input buffer, convert the 

character to the "converted to" code set and place it plus any lock-shift information into 
an output buffer. The descriptor cd identifies the conversion. The contents of inchar 
points to a single- or multi-byte character in the input buffer and inbytesleft points to 
the number of bytes from the input character to the end of the buffer. The contents of 
outchar points to the next available space in the output buffer and outbytesleft points to 
the number of the bytes from the next available space to the end of the buffer. While 
conversions are done from the input buffer to the output buffer, the contents of inchar, 
inbytesleft, outchar, and outbytesleft are incremented or decremented to reflect the 
current status of the input and output buffers. 

ICONV1 ( ) and ICONV2 ( ) are used where it is more efficient to handle single- and multi-byte characters 
separately. These routines do not check for lock-shift information. 

ICONV1 ( ) Convert single-byte characters in from according to the conversion identified by cd and 

return the converted value in to. ICONV1 ( ) assumes from contains only single-byte 
characters. 

ICONV2 ( ) Similarly convert double-byte characters in from according to the conversion identified 

by cd and return the converted value in to. ICONV2 ( ) assumes from contains only 
double-byte characters. 

The buflen argument in both ICONV1 ( ) and ICONV2 ( ) specifies the number of bytes that will be con- 
verted. 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUES 

iconvslze ( ) Returns the size of the conversion table in bytes if a table is needed and it exists. The 
function returns -1 if a table is needed and it does not exist. The function returns if a 
table is not needed. 

iconvopen ( ) Returns a conversion descriptor if successful. Otherwise, a (iconvd) -1 is returned. 



iconvclose() 
ICONVO 



ICONV1 ( ) 
ICONV2 ( ) 



Returns a non-negative number if successful. Otherwise a -1 is returned. 

returns if all characters from the input buffer are successfully converted and placed 
into the output buffer. ICONV( ) returns 1 if a multi-byte input character or a lock- 
shift sequence spans the input buffer boundary. No conversion is attempted on the 
character and the contents of inchar points to the start of the truncated character 
sequence. ICONV ( ) returns 2 if an input character does not belong to the "converted 
from" character set. No conversion is attempted on the character and the contents of 
inchar points to the start of the unidentified input character. ICONV ( ) returns 3 if 
there is no room in the output buffer to place the converted character. The converted 
character is not placed in the output buffer and the contents of inchar points to the start 
of the character sequence that caused the output buffer overflow. 

Both return the number of bytes converted if successful. Otherwise they return -1. 



EXAMPLES 

int 

convert ( tocode , fromcode, dl, d2) 

char * tocode; 

char * fromcode; 

int dl; 

int d2; 



/* tocode name */ 

/* fromcode name */ 

/* one -byte default character */ 

/* two-byte default character */ 
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extern void error ( ) ; 



/* local error message */ 



iconvd cd; 

int size; 

unsigned char * table; 

int bytesread; 

unsigned char inbuf [BUFSIZ] ; 

unsigned char * inchar; 

int inbytesleft; 

unsigned char outbuf [BUFSIZ] 

unsigned char *outchar; 

int outbytesieft; 



/* conversion descriptor */ 

/* size of translation table */ 

/* ptr to translation table */ 

/* num bytes read into input buffer */ 

/* input buffer */ 

/* ptr to input character */ 

/* num bytes left in input buffer */ 

/* output buffer */ 

/* ptr to output character */ 

/* num bytes left in output buffer */ 



/* create conversion table */ 

if ((size = iconvsize(tocode, fromcode) ) == BAD) { 

error (FATAL, BAD_SIZE) ; 
} 
else if (size == 0) { 

table = (unsigned char *) NULL; 
} 
else if ( (tables (unsigned char *)malloc( (unsigned int) size) )== (unsigned char *)NULL) 

error (FATAL, BAD_CREATE) ; 
} 

/* start up a conversion */ 

if ( (cd = iconvopen(tocode, fromcode, table, dl, d2)) == (iconvd) BAD) { 

error (FATAL, BAD_OPEN) ; 
} 

inchar = inbuf; 
inbytesleft =0; 
outchar = outbuf; 
outbytesieft = BUFSIZ; 



/* translate the characters */ 
for ( ;; ) { 

switch (ICONV(cd, & inchar, &inbyteslef t, & out char, &outbytesleft) ) { 

case 0: 

case 1: 



/* 
** 

** 

** 

** 

** 

** 



Done with buffer, empty buffer or character spans 
input buffer boundary. Move any remaining stuff 
to start of buffer, get more characters and 
reinitialize input variables. If at EOF, flush 
output buffer and leave; otherwise, continue to 
convert the characters. 



strncpy (inbuf, inchar, inbytesleft); 

if ( (bytesread=read( Input, inbuf + inbytesleft, 

perror("prog") ; 

return BAD; 



} 
if 



BUFSIZ-inbytesleft) ) < 0) < 



(! (inbytesleft += bytesread)) { 
if (write (1, outbuf, BUFSIZ 
perror ( "prog" ) ; 
return BAD; 
} 
goto END_CONVERSION; 



outbytesieft) < 0) { 
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} 

inchar = inbuf; 
break; 
case 2 j 

error ( FATAL , BAD_CONVBRS ION ) ; 
case 3 t 

/* 

** Full buffer or output character spans output buffer 
** boundary. Send the output buffer to stdout, 
** reinitialize the output variables - 
*/ 

if (write (1, outbuf, BUFSIZ - outbytesleft) < 0) { 
perror ( "prog" ) ; 
return BAD; 
} 

outchar = outbuf; 
outbytesleft = BUFSIZ; 
} 
} 
END_CONVERSION : 

/* end conversion & get rid of the conversion table */ 
if (iconvclose(cd) == BAD) { 

error ( FATAL , BAD_CLOSE ) ; 
} 
if (size) { 

free ((char *) table); 
} 

return GOOD; 
} 

AUTHOR 

iconv ( ) was developed by HP. 

SEE ALSO 

iconv(l). 
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NAME 

copysign(), copysignf(), drem(), finite(), finitef(), logb(), scalb() - exponent manipulations 

SYNOPSIS 

#include <math.h> 

double copysign( double x, double y); 

double drem(double x, double y) ; 

int finite (double x) ; 

double logb (double x) ; 

double scalb (double x, int n) ; 

float copysignf (float x, float y) ; 

int finitef (float x) ; 

DESCRIPTION 

These functions are required for, or recommended by, the IEEE-754 standard for floating-point arithmetic. 

copys ign ( ) returns x with its sign changed toy's. 

drem( ) returns the remainder r=x-n*y where n is the integer nearest the exact value of x/y; moreover, if 
\n-xly I = 1/2, then n is even. Consequently the remainder is computed exactly and \r\ < ly 1/2. But 
drem {x , ) is exceptional; see below under ERRORS. 

finite () returns 1 only when -INFINITY < x < +INFINITY. Otherwise it returns (i.e., when I re I = 
INFINITY or x is NaN). 

logb ( ) returns x's exponent n, a signed integer converted to double-precision floating point and chosen 
such that 1 < \x \/2**n < 2 unless x = or (only on machines that conform to the IEEE-754 standard) \x\ = 
INFINITY or x lies between and the underflow threshold. 

scalb ( ) returns x*(2**n) computed, for integer n, without first computing 2**ra . 

copysignf () and finitef () are float versions of copysign() and finite(). They are 
named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C 
standard. Programs must be compiled in ANSI mode (use the -Aa option) in order to use these functions; 
otherwise, the compiler promotes the float arguments to double, and the functions return incorrect 
results. 

DEPENDENCIES 
Series 300/400 

These functions are not supported on Series 300/400 systems. 

Series 700/800 

These functions are provided in the PA1.1 versions of the math library only. The +DA1 . 1 option (the 
default on Series 700 systems) links in a PA1.1 version automatically. A PA1.1 library can be linked in expli- 
citly. For more information, see the HP-UX Floating-Point Guide. 

ERRORS 

The IEEE-754 standard defines drem (at, ) and drem( INFINITY, y ) to be invalid operations that pro- 
duce a NaN. 

The IEEE-754 standard defines logb (±INPINITY) = +INFINITY and logb(0) = -INFINITY, and 
requires the latter to signal a division-by-zero exception. 

SEE ALSO 

isnan(3M), isinf(3M), fpclassify(3M). 
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NAME 

inet_addr(), inet_network(), inet_ntoa(), inet_makeaddr(), inet_lnaof( ), inet_netof() - Internet address 
manipulation routines 

SYNOPSIS 

#include <sys/socket .h> 
ttinclude <netinet/in.h> 
# include <arpa/inet .h> 

unsigned long inet_addr (const char *cp) ; 

unsigned long inet_network (const char *ep); 

char *inet_ntoa (struct in_addr in); 

struct in_addr inet_makeaddr (int net, int lna) ; 

int inet_lnaof (struct in_addr in); 

int inet_netof (struct in_addr in); 

DESCRIPTION 

inet_addr ( ) Interpret character strings representing numbers expressed in the Internet stan- 

inet_network ( ) dard "dot" notation. 

inet_addr ( ) returns numbers suitable for use as Internet addresses. 

inet_network ( ) returns numbers suitable for use as Internet network 
numbers> 

Return values can be assigned to a struct in_addr (defined in 
/usr /include/net inet /in . h) by using a technique similar to the following: 

struct in_addr addr; 
char *cp; 

addr.s_addr = inet_addr (cp) ; 

inet_ntoa ( ) Take an Internet address and return an ASCII string representing the address in "." 

(dot) notation. 

inet_makeaddr ( ) Take an Internet network number and a local network address and construct an 
Internet address from it. 

inet_netof ( ) Break apart Internet host addresses, returning the network number part. 

inet_lnaof ( ) Break apart Internet host addresses, returning the local network address part. 

All Internet addresses are returned in network order (bytes ordered from left to right). All network 
numbers and local address parts are returned as machine-format integer values. Bytes in HP-UX systems 
are ordered from left to right. 

Internet Addresses: 

Values specified using dot notation take one of the following forms: 

a.b.c.d 
a.b.c 
a.b 
a 

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the 
four bytes of an Internet address. 

When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the 
right-most two bytes of the network address. This makes the three-part address format convenient for 
specifying Class B network addresses as in 1 2 8 . net . hos t . 

When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the 
right-most three bytes of the network address. This makes the two-part address format convenient for 
specifying Class A network addresses as in net .host. 
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When only one part is given, the value is stored directly in the network address without any byte rear- 
rangement. 

All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C 
language (i.e., a leading Ox or OX implies hexadecimal; a leading implies octal; otherwise, the number is 
interpreted as decimal). 

T» , B"r>TTT»'KJ 1TAT TTE1 

inet_addr ( ) and inet_network ( ) return -1 for malformed requests. 

WARNINGS 

The string returned by inet_ntoa ( ) resides in a static memory area and must be saved if needed for 
later use. 

ATTTTI/VD 

These inet routines were developed by the University of California, Berkeley. 

SEE ALSO 

gethostent(3N), getnetent(3N), hosts(4), networks(4). 
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NAME 

initgroups() - initialize group access list 

SYNOPSIS 

#include <unistd.h> 

int initgroups (const char *name, gid_t basegid); 

DESCRIPTION 

initgroups ( ) reads the login group file, /etc/logingroup, and sets up the group access list for the 
user specified by name, using the setgroups(2) system call. If the value of basegid is zero or positive, it is 
automatically included in the groups list. Typically this value is given as the group number from the pass- 
word file. If the login group file does not exist or is empty, basegid is the only member of the list. 

RETURN VALUE 

initgroups ( ) returns - 1 if it was not invoked by a user with appropriate privileges. 

WARNINGS 

initgroups ( ) uses the routines based on getgrent(3C). If the invoking program uses any of these rou- 
tines, the group structure is overwritten by the call to initgroups () . Subsequent calls to init- 
groups ( ) with the same name parameter override the actions of previous calls. 

On many systems, no one seems to keep /etc/logingroup up to date. 

NETWORKING FEATURES 

NFS 

If /etc/logingroup is linked to /etc/group, initgroups ( ) tries to use the Network Informa- 
tion Service (NIS) for entries beginning with a plus sign (+). If group membership for name is managed by 
NIS, and no NIS server is able to respond, a call to initgroups ( ) does not return until a server does 
respond. This causes commands such as login(l) and su(l) to wait indefinitely. 

See group(4) for proper syntax and operation. 

AUTHOR 

initgroups ( ) was developed by the University of California, Berkeley. 

FILES 

/etc/logingroup login group file 

SEE ALSO 

login(l), su(l), getgroups(2), setgroups(2), group(4). 
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NAME 

initopt() - initialize a NetlPC option buffer 

SYNOPSIS 

ftinclude <sys/ns_lpc.h> 

void initopt (short opt[], short maxoptions, short *result); 

DESCRIPTION 

initopt ( ) must be used to initialize a NetlPC option buffer. Options can be added to the buffer by cal- 
ling addopt ( ) and read by calling readopt ( ) (see addopt(3N) and readopt(3N)). 

The maxoptions parameter specifies the maximum number of options that can be placed in the buffer. For 
example, if maxoptions specifies one, then one option can be added to the buffer. If three is specified then 
three options can be added. Options are indexed starting from zero. 



Each time a NetlPC options buffer is to be used, it should be initialized to the number of options to be 
added. If fewer options are added than the buffer is initialized for, a resulting unitialized option may cause 
an error. A given buffer can be reused, but should be reinitialized before each use. 

A NetlPC option buffer consists of space for overhead and space for options, opt overhead ( ) returns 
the number of bytes needed in a buffer for a given number of options (see optoverhead (3N)). The bytes 
needed for option data depends upon the number and type of the options to be added, and must be calcu- 
lated by the programmer. An option buffer can be larger than necessary. 

Parameters 

opt (input parameter) 

The address of the buffer to be initialized. 

maxtoptions (input parameter) 

The maximum number of options to be added to the buffer. 

result (output parameter) 

The result code returned. Refer to diagnostics section below for more information. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

DIAGNOSTICS 

initopt ( ) sets result to the value indicated when the following conditions are encountered: 

[NSR_ADDR_OPT] The options parameter is null. 

[NSR_NO_ERROR] The call was successful. 

[NSR_OPT_TOTAL] The num_entries parameter is negative. 

AUTHOR 

initopt ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
ipcerrmsg(3N), optoverhead(3N), readopt(2). 
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NAME 

io_burst() - perform low-overhead I/O on an HP-IB/GPIO channel 

SYNOPSIS 

ttinclude <dvio.h> 

int io_burst (int eid, int flag); 

DESCRIPTION 

io_burst ( ) is used to perform low-overhead burst transfers on the specified HP-IB, or GPIO interface, eid 
is the entity identifier for an open HP-IB or GPIO device file returned by a previous call to open ( ) , dup ( ) , 
creat ( ) , or f cnt 1 ( ) with an FDUPD command option, flag is an integer which, if non-zero, enables 
burst mode or, if zero, disables it. 

In burst mode, memory-mapped I/O address space assigned to the interface card select code is mapped 
directly into user space such that data can be transferred directly between user memory and the interface 
card, eliminating the need for kernel calls and the associated overhead. Burst mode affects only read ( ) , 
write ( ) , gpio_get_st atus ( ) , gpio_set_ct 1 ( ) , hpib_io ( ) , and hpib_send_cmd ( ) calls. 
All other operations are unaffected. When burst mode is enabled, the interface is locked so that no other 
process can access it until burst mode is disabled. When burst mode is disabled, the interface is reset (see 
io_reset(3I)). 

RETURN VALUE 

io_burst ( ) returns zero if successful or -1 if an error is detected. 

ERRORS 

io_burst ( ) fails under any of the following circumstances and sets errno (see errno{2)) to one of the 
following values: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to an HP-IB or GPIO device special file. 

[EIO] A timeout occurred during the call to ioburst ( ) (Series 300/400 only). 

Enabling burst mode locks the interface from all other processes, so it should never be used with any inter- 
face that supports a system disk or swap device. 

Timeouts for read(), write (), gpio_get_status ( ), gpio_set_ctl ( ), hpib_io(), and 
hpib_send_cmd ( ) do not work while in burst mode, but these commands can be interrupted by signals. 

AUTHOR 

io_burst ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), read(2), write(2), gpio_get_status(3l), gpio_set_ctl(3l), hpib_io(3l), 
hpib_send_cmd(3l), io_reset(3l). 
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NAME 

io_dma_ctl() - control DMA allocation for an interface 

SYNOPSIS 

#include <sys/dil.h> 

int io_dma_ctl (int eid, int mode); 

DESCRIPTION 

io_dma_ct 1 ( ) is used to control system DMA allocation for a specific interface, eid is the entity identifier 
for an open HP-IB, Centronics-compatible parallel, or GPIO device file returned by a previous call to 
open ( ) , dup ( ) , creat ( ) , or f cntl ( ) with an FDUPD command option. 

The mode parameter describes what type of DMA allocation the system should use for the interface associ- 
ated with eid. mode is determined by selecting one of flags from the following list in <sys/dii .h>: 

One and only one of the following flags must be specified: 

DMA_ACTIVE Inform the DMA subsystem that this interface intends to use DMA and 

requires higher priority than slow devices. This is the level of DMA alloca- 
tion used by CS/80, Amigo, and SCSI devices. 

DMA_UNACTIVE Remove the effect of a previous DMA_ACTIVE. 

DMA_RESERVE Guarantee that a DMA channel will remain unlocked for future requests 

for DMA by all devices on this interface. 

DMAJJNRESERVE Remove the effect of a previous DMA_RESERVE. 

DMA_LOCK Lock a DMA channel for exclusive use by all devices on this interface. 

DMA_UNLOCK Unlock a DMA channel locked by this interface. 

RETURN VALUE 

io_dma_ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

io_dma_ctl ( ) fails under the following circumstances, and sets errno (see errno(2J) to the value indi- 
cated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a Device I/O Library-compatible device file. 

[EIO] A timeout occurred (Series 300/400 only). 

[EINTR] Request was interrupted by a signal. 

[EINVAL] Interface was unable to reserve or lock a DMA channel. 

WARNINGS 

Series 300/400 systems have only two DMA channels. Use of DMA_LOCK could limit access to DMA 
resources by system disks, resulting in lower system performance. 

AUTHOR 

io_dma_ct 1 ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2). 
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NAME 

io_eol_ctl() - set up read termination character on special file 

SYNOPSIS 

#include <dvio.h> 

int io_eol_ctl (int eid, int flag, int match); 

DESCRIPTION 

io_eol_ctl ( ) specifies a character to be used in terminating a read operation from the specified file 
(entity identifier). 

eid is an entity identifier of an open HP-IB raw bus, Centronics-compatible parallel, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, flag is an integer that enables or disables 
character-match termination. A non-zero value enables character-match termination, while a zero value 
disables it. match is an integer containing the numerical equivalent of the termination character, match is 
ignored if flag is zero. When in 8-bit mode, the lower 8 bits of match are used as the termination character. 
In 16-bit mode, the lower 16 bits are used. 

Upon opening a file, the default condition is character-match termination disabled. When enabled, the H 

character specified by match is checked for during read operations. The read is terminated upon receipt of M 

this character, or upon any of the other termination conditions normally in effect for this file. Examples of 
other conditions are satisfying the specified byte count, and receiving a character when the EOI line is 
asserted (HP-IB). When the read is terminated by a match character, this character is the last character 
returned in the buffer. 

Entity identifiers for the same device file obtained by separate open ( ) calls have their own termination 
characters associated with them. Entity identifiers for the same device file inherited by a f ork( ) call 
share the same termination character. In the latter case, if one process changes the termination character, 
the new termination character is in effect for all such entity identifiers. 

RETURN VALUE 

io_eol_ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

io_eol_ctl ( ) fails under the following circumstances, and sets errno (see errno(2)) to the value indi- 
cated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a channel device file. 

AUTHOR 

io_eol_ctl ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), io_width_ctl(3l). 
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NAME 

io_get_term_reasoii() - determine how last read terminated 

SYNOPSIS 

# include <dvio.h> 

int io_get_term_reason(int eid) ; 

DESCRIPTION 

io_get_term_reason ( ) returns the termination reason for the last read made on this entity id. eid is 
an entity identifier of an open HP-IB raw bus, Centronics-compatible parallel interface, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call. 

All entity identifiers descending from an open() request (such as from dup ( ) or fork() ) set this 
status. For example, if the calling process had opened this entity identifier and later forked, the status 
returned would be from the last read done by either the calling process or its child. 

RETURN VALUE 

io_get_term_reason ( ) returns a value indicating how the last read on the specified entity identifier 
was terminated. This value is interpreted as follows (note that combinations are possible): 

Value Description 

-1 An error was encountered while making this function request. 

Last read encountered some abnormal termination reason not covered by any 
of the other reasons. 

1 Last read terminated by reading the number of bytes requested. 

2 Last read terminated by detecting the specified termination character. 

4 Last read terminated by detecting some device-imposed termination condi- 

tion. Examples are: EOI for HP-IB, PSTS line on GPIO, or some other end-of- 
record condition, such as the physical end-of-record mark on a 9-track tape. 

ERRORS 

io_get_term_reason ( ) fails under the following circumstances, and sets errno (see errno(2)) to the 
value indicated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a channel device file. 

DEPENDENCIES 
Series 300/400: 

For the GPIO interface, PSTS is checked only at the beginning of a transfer. An interrupt caused by an EIR 
also terminates a transfer. The value of the termination reason in this case is also 4. 

For the Centronics-compatible parallel interface, a termination reason value of 4 indicates that the transfer 
terminated because the peripheral asserted the ACK line. 

AUTHOR 

io_get_term_reason ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), read(2), io_eol_ctl(3l). 
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NAME 

io_interrupt_ctl() - enable/disable interrupts for the associated eid 

SYNOPSIS 

#include <dvio.h> 

int io_interrupt_ctl (int eid, int enable_f lag) ; 

DESCRIPTION 

eid is the entity identifier of an open HP-IB raw bus, Centronics-compatible parallel, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, flag is an integer which enables or dis- 
ables interrupts for the associated eid. A non-zero value enables interrupts. 

Interrupts can be disabled or enabled as desired. When an interrupt occurs for a given eid the interrupts 
associated with this eid are automatically disabled from recurring. To re-enable interrupts for this eid, use 
io_interrupt_ctl ( ) . 

RETURN VALUE 

io_interrupt_ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

io_interrupt_ctl ( ) fails under the following situations, and sets errno (see errno(2)) to the value 
indicated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a device that supports interrupts. 

[EINVAL] No interrupt conditions were specified for this eid. 

AUTHOR 

io_in.terrupt_ctl ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), io_on_interrupt(3l). 
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NAME 

io_lock, io_unlock - lock and unlock an interface 

SYNOPSIS 

#include <dvio.h> 

int io_lock(int eid) ; 
int io_unlock(int eid); 

DESCRIPTION 

lolock() attempts to lock the interface associated with an entity identifier for the requesting process. 
Locking an interface gives exclusive use of the interface associated with the eid to the requesting process, 
thus avoiding unintended interference from other processes during a series of separate I/O requests. All 
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eid is an entity identifier of an open HP-IB, Centronics-compatible parallel, or GPIO device file, obtained 
from an open( ) , dup ( ) , f cntl ( ) , or creat ( ) call (see open{2), dup(2), fcntl(2), and creat{2)). 

Other processes that attempt to access or lock a locked interface either return an error or sleep until the 
interface becomes unlocked. The action taken is determined by the current setting of the 0_NDELAY flag 
(see open(2). If the 0_NDELAY flag is set, accesses to a locked interface fail and set errno to indicate the 
error. If the 0_NDELAY flag is not set, accesses to a locked interface block until the interface is unlocked, 
the current timeout expires, or the request is interrupted by a signal. 

A lock is associated with a process, not with an eid. Locking an interface with a particular eid does not 
prevent the process that owns the lock from accessing the interface through another eid. A lock associated 
with an eid is not inherited by a child process during a fork ( ) (see fork{2)). 

Nested locking is fully supported. If a process owns a locked interface and calls a generic subroutine that 
does a lock and unlock, the calling process does not lose its lock on the interface. Locking requests produced 
by a given process for an interface already locked by the same process increment the current lock count for 
that interface. 

io_unlock() allows a process to remove a lock from the interface associated with the eid. A locked 
interface can be unlocked only by the process that directly owns the lock. When an unlock operation is 
applied to an eid that is currently multiply locked, the unlock operation decrements the current lock 
counter for that interface, and the interface remains locked until the count is reduced to zero. 

RETURN VALUE 

io_lock( ) and io__unlock( ) return the integer value of the current lock count if successful. A lock 
count greater than zero indicates that the interface is still locked. A lock count of zero indicates that the 
interface is no longer locked. A -1 indicates that an error has occured. 

ERRORS 

io_lock() and io_unlock() fail in the following situations, and set errno (see errno{2)) to the 
value indicated: 

[EACCES] An attempt was made to lock an interface locked by another process with 0_NDELAY 

set. 

[EBADF] eid does not refer to an open file. 

[EINTR] A signal was caught while attempting to perform the lock with 0_NDELAY clear. 

[EINVAL] an attempt was made to unlock when the interface is not locked. 

[ETIMEDOUT] A timeout occured while attempting to perform the lock with O.NDELAY clear. 

[ENOTTY] eid does not refer to a channel device file. 

[EPERM] An attempt was made to unlock when lock is not owned by this user. 

WARNINGS 

io_lock ( ) provides a mandatory lock enforced by the system, and should not be used with any interface 
supporting a system disk or swap device. 

Series 800: 

Processes that lock HP-IB or GPIO interfaces should clear all locks before exiting. The driver attempts to 
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clear them if the process terminates unexpectedly; however, a lock might be left outstanding if the locker 
dies after creating new file descriptors (via fork ( ) or dup ( ) ) that refer to the same device file. Ensuring 
that all open file descriptors on a given interface are closed remedies the situation. 

DEPENDENCIES 
Series 300/400: 

io_lock ( ) and io_unlock ( ) return [EIO] if a timeout occurs. 

AUTHOR 

io_lock ( ) and io_unlock ( ) were developed by HP. 

SEE ALSO 

io_timeout_ctl(3l), open(2). 
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NAME 

io_on_interrupt() - device interrupt (fault) control 

SYNOPSIS 

#include <dvio.h> 

int (*io_on_lnterrupt ( 

int eid, 

struct lnterrupt_struct *causevec, 

int (*handler) (int, struct interrupt_struct *) 
))(int, struct interrupt_struct *); 

DESCRIPTION 

eid is an e 

file, obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call. 

causevec is a pointer to a structure of the form: 

struct interrupt_struct { 

integer cause; 

integer mask; 

}; 

The inter rupt_struct structure is defined in the file dvio . h. 

cause is a bit vector specifying which of the interrupt or fault events can cause the handler routine to be 
invoked. The interrupt causes are often specific to the type of interface being considered. Also, certain 
exception (error) conditions can be handled using the io_on_interrupt () capability. Specifying a 
zero valued cause vector effectively turns off the interrupt for that eid. 

The mask parameter is used when an HP-IB parallel poll interrupt is being defined, mask is an integer that 
specifies which parallel poll response lines are of interest. The value of mask is viewed as an 8-bit binary 
number where the least significant bit corresponds to fine DIOl; the most significant bit to line DI08. For 
example, to activate an interrupt handler when a response occurs on lines 2 or 6, the correct binary number 
is 00100010. Thus a hexadecimal value of 22 is the correct argument value for mask. 

When an enabled interrupt condition on the specified eid occurs, the receiving process executes the 
interrupt-handler function pointed to by handler. The entity identifier eid and the interrupt condition 
cause are returned as the first and second parameters, respectively. 

When an interrupt that is to be caught occurs during a read ( ) , write ( ) , open ( ) , or ioct 1 ( ) system 
call on a slow device such as a terminal (but not a file), during a pause ( ) system call, a sigpause ( ) 
system call, or a wait ( ) system call that does not return immediately due to the existence of a previously 
stopped or zombie process, the interrupt handling function is executed and the interrupted system call 
returns -1 to the calling process with errno set to EINTR. 

Interrupt handlers are not inherited across a fork ( ) . eids for the same device file produced by dup ( ) 
share the same handler. 

An interrupt for a given eid is implicitly disabled after the occurrence of the event. The interrupt condition 
can be re-enabled by using io_interrupt_ct 1 ( ) (see ioJnterrupt_ctl(3I)). 

When an event specified by cause occurs, the receiving process executes the interrupt handler function 
pointed to by handler. When the handler returns, the user process resumes at the execution point where 
the event occurred. 

Two parameters are passed to handler: the eid associated with the event, and a pointer to a causevec 
structure. The cause of the interrupt can be determined by the value returned in the cause field of the 
causevec structure (more than 1 bit can be set, indicating that more than 1 interrupting condition has 
occurred). If the interrupt handler was invoked due to a parallel poll interrupt, the mask field of the 
causevec structure contains the parallel poll response byte. 

HP-IB Interrupts 

This section describes interrupt causes specific to an HP-IB device. For an HP-IB device, the cause is a bit 
vector which is used as follows. To enable a given event, the appropriate bit (in cause), shown below, must 
be set to 1: 
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SRQ SRQ and active controller 

TLK Talker addressed 

LTN Listener addressed 

TCT Controller in charge 

IFC IFC has been asserted 

REN Remote enable 

DCL Device clear 

GET Group execution trigger 

PPOLL Parallel poll 

GPIO Interrupts 

This section describes interrupt causes specific to a GPIO device. For a GPIO device, cause is a bit vector 
which is used as follows. To enable a given event, the appropriate bit (in cause), shown below, must be set 
tol: 

EIR External interrupt 

SIEO Status line 
SIE1 Status line 1 

Parallel Interrupts 

This section describes interrupt causes specific to a Centronics-compatible parallel device. For a 
Centronics-compatible parallel device, cause is a bit vector which is used as follows. To enable a given 
event, the appropriate bit (in cause), shown below, must be set to 1: 

NERROR Nerror interrupt 

SELECT Select interrupt 

PE Paper error interrupt 

RETURN VALUE 

io_on_interrupt ( ) returns a pointer to the previous handler if the new handler is successfully 
installed; otherwise it returns a -1 and sets errno to indicate the error. 

ERRORS 

io_on_interrupt ( ) fails for any of the following reasons and sets errno to the value indicated: 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see iolock (31)). 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a GPIO, Centronics-compatible parallel, or a raw HP-IB device file. 

[EFAULT] handler points to an illegal address. The reliable detection of this error is implemen- 

tation dependent. 

[EFAULT] causevec points to an illegal address. The reliable detection of this error is implemen- 

tation dependent. 

DEPENDENCIES 
Series 300/400: 

For the HP 98622 GPIO interface, only the EIR interrupt is available. For the HP 98265A/B HP-IB interface, 
the IFC and GET interrupts are not provided. 

Series 800: 

For the HP 27114 AFI interface, only the EIR interrupt is available. 

AUTHOR 

io_on_interrupt ( ) was developed by HP. 

SEE ALSO 

dup(2), creat(2), fcntl(2), open(2), pause(2), sigpause(2), io_interrupt_ctl(3I). 
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NAME 

io_reset() - reset an I/O interface 

SYNOPSIS 

#include <dvio.h> 

int io_reset(int eid) ; 

DESCRIPTION 

io_reset ( ) resets the interface associated with the device file that was opened. It also pulses the peri- 
pheral reset line on the GPIO interface, or the IFC line on the HP-IB. eid is an entity identifier of an open 
HP-IB, Centronics-compatible parallel interface, or GPIO device file obtained from an open ( ) , dup ( ) , 
f cntl ( ), or creat ( ) call. 

io_reset ( ) also causes an interface to go through its self-test, and returns a failure indication if the 
interface fails its test. 

RETURN VALUE 

io_reset ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

lo__reset () fails under the following circumstances, and sets errno (see errno(2)) to the value indi- 
cated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a channel device file. 

[EIO] Interface could not be reset or failed self-test. 

[EACCES] The interface associated with this eid is locked by another process and 0_NDELAY is 

set for this eid (see iojock (31)). 

DEPENDENCIES 
Series 300/400: 

When an HP-IB interface is reset, the interrupt mask is set to 0, the parallel poll response is set to 0, the 
serial poll response is set to 0, the HP-IB address is assigned its powerup default value, the IFC line is 
pulsed (if system controller), the card is put on line, and REN is set (if system controller). 

When a GPIO interface is reset, the peripheral reset line is pulled low, the PCTL line is placed in the clear 
state, and if the DOUT CLEAR jumper is installed, the data out fines are all cleared. The interrupt enable 
bit is also cleared. 

Interface self-test is not supported. 

AUTHOR 

io_reset ( ) was developed by HP. 
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NAME 

io_speed_ctl() - inform system of required transfer speed 

SYNOPSIS 

ttinclude <dvio.h> 

int io_speed_ctl (int eid, int speed); 

DESCRIPTION 

io_speed_ctl ( ) selects the data transfer speed for a data path used for a particular interface. The 
transfer method (i.e., DMA or fast-handshake) chosen by the system is determined by the speed require- 
ments. 

eid is an entity identifier of an open HP-IB raw bus, Centronics-compatible parallel, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, speed is an integer specifying the data 
transfer speed in Kbytes per second (one Kbyte equals 1024 bytes). 

RETURN VALUE 

io_speed_ctl ( ) returns if successful, and -1 otherwise. 

ERRORS 

io_speed_ct 1 ( ) fails under the following condition, and sets errno to the value indicated: 

[ENOTTY] eid does not refer to channel device file. 

[EBADF] eid does not refer to an open file. 

DEPENDENCIES 
Series 300/400: 

For values of speed less than 7, the system uses an interrupt transfer. For larger values, DMA is used if 
available; otherwise, the system uses an interrupt transfer. The default transfer method is DMA. 

Series 800: 

DMA is the only supported transfer method. 

AUTHOR 

io_speed_ct 1 ( ) was developed by HP. 
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NAME 

io_timeout_ctl() - establish a time limit for I/O operations 

SYNOPSIS 

#include <dvio.h> 

int io_timeout_ctl(int eid, long time); 

DESCRIPTION 

io_timeout_ctl () assigns a timeout value to the specified eid (entity identifier), eid is an entity 
identifier of an open HP-IB raw bus, auto-addressed, Centronics-compatible parallel, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cnt 1 ( ) , or creat ( ) call, time is a long integer value specifying the 
length of the timeout in microseconds. A value of for time specifies no timeout (infinity). 

This timeout applies to future read and write requests on this eid . If a read or write request does not com- 
plete within the specified time limit, the request is aborted and returns an error indication. If an operation 
is aborted due to a timeout, errno is set to ETIMEDOUT. 

Although the timeout value is specified in microseconds, the resolution of the timeout is system-dependent. 
For example, a particular system might have a resolution of 10 milliseconds, in which case the specified 
timeout value is rounded up to the next 10 msec boundary. A timeout value of zero means that the system 
never causes a timeout. When a file is opened, a zero timeout value is assigned by default. 

Entity identifiers for the same device file obtained by separate open ( ) calls have their own timeout 
values associated with them. Entity identifiers for the same device file obtained by dup ( ) or inherited by 
a fork ( ) call share the same timeout value. In the latter case, if one process changes the timeout, the 
new timeout is in effect for all such eids. 

RETURN VALUE 

lo__t lmeout_ctl ( ) returns (zero) if successful, or -1 if an error was encountered. 

ERRORS 

io_t imeout_ctl ( ) fails under the following circumstances, and sets errno (see errno(2)) to the value 
indicated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a channel device file. 

DEPENDENCIES 
Series 300/400: 

System timeout resolution is 20 msec. 

EIO is returned if an operation is aborted due to a timeout. 

AUTHOR 

io_t lmeout_ctl ( ) was developed by HP. 
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NAME 

io_width_ctl - set width of data path 

SYNOPSIS 

ttinclude <dvio.h> 

int io_width_ctl(int eid, int width); 

DESCRIPTION 

io_width_ctl ( ) enables you to select the width of the data path to be used for a particular interface. 
eid is an entity identifier of an open HP-IB, Centronics-compatible parallel interface, or GPIO device file 
obtained from an open ( ) , dup ( ) , f cntl ( ) , or creat ( ) call, width is an integer specifying the width 
of the data path in bits. 

An error is given if an invalid width is specified. Specifying a width with this function sets the width for all 
users of the device file associated with the given entity id. When first opened, the default width is 8 bits. 

For the GPIO interface only widths of 8 and 16 bits are currently supported. For the HP-IB and Centronics- 
compatible parallel interfaces, only a width of 8 bits is supported. _ 

RETURN VALUE | 

io_width_ctl ( ) returns if successful, and -1 if an error was encountered. 

ERRORS 

io_width_ctl () fails under the following circumstances and sets errno (see errno(2)) to the value 
indicated: 

[EBADF] eid does not refer to an open file. 

[ENOTTY] eid does not refer to a channel device file. 

[EINVAL] the specified width is not supported on this device file. 

AUTHOR 

io_width_ct 1 ( ) was developed by HP. 
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NAME 

ipcerrmsg(), ipcerrstr() - provide text describing a NetlPC error number 

SYNOPSIS 

#include<sys/ns_ipc.h> 

char *ipcerrstr (int error); 

void ipcerrmsg ( 
int error, 
char *buffer, 
int *len, 
int *result) ; 

DESCRIPTION 

ipcerrstr ( ) Takes as input a NetlPC error number and returns a pointer to a NULL-terminated 

string describing the error. If the error is unknown, NULL is returned. 

ipcerrmsg ( ) Copies an error message for a NetlPC error into a supplied buffer. It copies len-1 

bytes into the buffer to ensure that the result is null-terminated. 

ipcerrmsg ( ) parameters are as follows: 

error (input parameter) The NetlPC error number to be described. 

buffer (input parameter) A data buffer into which the description is to be 

copied. 

len (input/output parameter) A pointer to the length of the buffer. On 

output it contains the length of the description. 

result (output parameter) The result code returned. Refer to ERRORS 

below for more information. 

RETURN VALUE 

ipcerrstr ( ) returns NULL if the error number is unknown. 

ipcerrmsg ( ) returns results in the result parameter. 

ERRORS 

ipcerrmsg ( ) sets result to the value indicated when any of these conditions are encountered: 

[NSR_NO_ERROR] The call was successful. 

[NSR_ERRNUM] An unknown error number was passed to ipcerrms g . 

AUTHOR 

ipcerrmsg ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), optoverhead(3N), readopt(3N). 
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NAME 

is_68010_present(), is_68881_present(), is_98635A_present(), is_98248A_present( ) - check for presence of 
hardware capabilities 

SYNOPSIS 

#include <unistd.h> int is_68010_present (void) ; 

int is_68881_present (void) ; 
int is_98635A_present (void) ; 
int is_98248A_present (void) ; 

DESCRIPTION 

Each function checks for the presence of a specified hardware capability, returning 1 if it exists or if it 
does not. 

RETURN VALUE 

The value 1 is returned by: 

is_68010_present ( ) if the system has an MC68010 as its CPU. 

is_6 88 81_present ( ) if an MC68881 floating-point coprocessor is present. 

is_9 8635A_present ( ) if an HP98635A floating-point accelerator has been installed. 

is_9 824 8A_present ( ) if an HP98248A floating-point accelerator has been installed. 

AUTHOR 

is_hw_present ( ) was developed by HP. 
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NAME 

isinf(), isinfl() - test for INFINITY functions 

SYNOPSIS 

#include <math.h> 

int isinf (double x) ; 
int isinf f (float x) ; 

DESCRIPTION 

isinf ( ) returns a positive integer if* is +INFINITY, or a negative integer if x is -INFINITY. Otherwise it 
returns zero. 

isinf f ( ) is the float version of isinf ( ) . It is named in accordance with the conventions specified 
in the "Future Library Directions" section of the ANSI C standard. Programs must be compiled in ANSI 
mode (use the -Aa option) in order to use this function; otherwise, the compiler promotes the float 
argument to double, and the function returns incorrect results. 

DEPENDENCIES 
Series 300/400 

isinf f ( ) is not supported on Series 300/400 systems. 

Series 700/800 

isinf f ( ) is provided in the PA1.1 versions of the math library only. The +DA1 . 1 option (the default on 
Series 700 systems) links in a PAl.l version automatically. A PAl.l library can be linked in explicitly. For 
more information, see the HP-UX Floating-Point Guide. 

SEE ALSO 

isnan(3M), fpclassify(3M), ieee(3M). 
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NAME 

isnan( ), isnanf( ) - test for NaN functions 

SYNOPSIS 

ttinclude <math.h> 

int isnan(double x) ; 
int isnanf (float x) ; 

DESCRIPTION 

isnan ( ) returns a nonzero integer if x is NaN (not-a-number). Otherwise it returns zero. 

isnanf ( ) is the float version of lsnan ( ) . Programs must be compiled in ANSI mode (use the -Aa 
option) in order to use this function; otherwise, the compiler promotes the float argument to double, 
and the function returns incorrect results. 

DEPENDENCIES 
Series 300/400 

Isnanf ( ) is not supported on Series 300/400 systems. 

Series 700/800 

isnanf () is not specified by any standard; however, it is named in accordance with the conventions 
specified in the "Future Library Directions" section of the ANSI C standard. It is provided in the PAl.l ver- 
sions of the math library only. The +DA1 . 1 option (the default on Series 700 systems) finks in a PAl.l ver- 
sion automatically. A PAl.l library can be linked in explicitly. For more information, see the HP-UX 
Floating-Point Guide . 

SEE ALSO 

isinf(3M), fpclassify(3M), ieee(3M). 

STANDARDS CONFORMANCE 

isnan ( ) in libm.a: AES, XPG3 
isnan ( ) in libM.a: AES, XPG3, XPG4 
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NAME 

l3tol(), ltol3() - convert between 3-byte integers and long integers 

SYNOPSIS 

#include <stdlib.h> 

void 13tol(long int *lp, const char *cp, int n) ; 
void ltol3 (char *cp, const long int *lp, int n) ; 

DESCRIPTION 

13tol ( ) Convert a list of n three-byte integers packed into a character string pointed to by cp into a 

list of long integers pointed to by Ip. 

It ol 3 ( ) Perform the reverse conversion from long integers (Ip) to three-byte integers (cp). 

These functions are useful for file-system maintenance where the block numbers are three bytes long. 

SEE ALSO 

fs(4). 

WARNINGS 

Because of possible differences in byte ordering, the numerical values of the long integers are machine- 
dependent. 

STANDARDS CONFORMANCE 

13tol():XPG2 

lto!3():XPG2 
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NAME 

langinfoO, langtoidO, idtolangO, currlangid() - NLS information about native languages 

SYNOPSIS 

ttinclude <langinfo.h> 

char *langinfo(int langid, nl_item item); 
int langtoid (const char *langname) ; 
char *idtolang(int langid); 
int curr langid (void) ; 

DESCRIPTION 

Note: All functions defined on this page are obsolete. Use of nl_langinfo(SC) is recommended as a replace- 
ment for langinf o ( ) . 

langinf o ( ) returns a pointer to a null-terminated string containing information relevant to a particular 
language or cultural area defined in the program's locale (see setlocale(3C)). langinf o ( ) effectively 
calls langinit ( ) (see nl_init(3C)) to load the program's locale according to the language specified by 
langid. If langid or item (or both) is bad, langinf o ( ) returns a pointer to a NULL string. 

currlangid() looks for a LANG string in the user's environment. If it finds one, currlangid() 
returns the corresponding integer listed in lang(5). Otherwise, it returns to indicate a default to native- 
computer, the method used before NLS was available. 

idtolang ( ) takes the integer langid and attempts to return the corresponding character string defined 
in lang(5). If langid is not found, an empty string is returned. 

langtoid ( ) is the inverse of idtolang ( ) : it attempts to convert a string to a language ID, returning 
to indicate native-computer if no match is found. 

EXTERNAL INFLUENCES 
Locale 

The string returned by langinf o ( ) for a particular item is determined by the locale category specified 
for that item in langinfo(S). 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

WARNINGS 

langinf o ( ) returns a pointer to a static area that is overwritten on each call. 

AUTHOR 

langinf o ( ) was developed by HP. 

SEE ALSO 

nl_init(3C), nl_langinfo(3C), setlocale(3C), hpnls(5), lang(5), langinfo(5). 
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NAME 

_ldecvt(), _ldfcvt(), _ldgcvt() - convert long-double floating-point number to string 

SYNOPSIS 

#include <stdlib.h> 

char *_ldecvt ( long_double value, 
char *_ldfcvt (long_double value, 
char *_ldgcvt (long_double value, 

DESCRIPTION 

_ldecvt ( ) converts value to a null-terminated string of ndigit digits and returns a pointer to the 
string. The high-order digit is non-zero, unless the value is zero. The low-order digit is 
rounded. The position of the radix character relative to the beginning of the string is stored 
indirectly through decpt (negative means to the left of the returned digits). The radix char- 
acter is not included in the returned string. If the sign of the result is negative, the word 
pointed to by sign is non-zero; otherwise it is zero. 

_ldf cvt ( ) is identical to _ldecvt ( ) , except that the correct digit has been rounded for printf %Lf 
(Fortran F-format) output of the number of digits specified by ndigit. 

_ldgcvt ( ) Convert the value to a null-terminated string in the array pointed to by buf and return buf. 
It produces ndigit significant digits in Fortran F-format if possible, or E-format otherwise. 
A minus sign, if required, and a radix character are included in the returned string. Trail- 
ing zeros are suppressed. The radix character is determined by the currently loaded NLS 
environment (see setlocale (3 C)). If setlocale() has not been called successfully, the 
default NLS environment, "C" is used (see langih)). The default environment specifies a 
period (.) as the radix character. 

RETURN VALUE 

NaN is returned for Not-a-Number, and +INPINITY is returned for Infinity. 

WARNINGS 

The values returned by _ldecvt ( ) and _ldf cvt ( ) point to a single static-data array whose content is 
overwritten by each call. 

AUTHOR 

_ldecvt ( ) , _ldf cvt ( ) , and _ldgcvt ( ) were developed by HP. 

SEE ALSO 

setlocale(3C), printf(3S), hpnls(5), lang(5). 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category determines the radix character. 

International Code Set Support 

Single-byte character code sets are supported. 
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NAME 

localeconv() - query the numeric formatting conventions of the current locale 

SYNOPSIS 

ttinclude < locale. h> 

struct lconv *localeconv(vold) ; 

DESCRIPTION 

localeconv() sets the components of an object of type struct lconv (defined in <locale.h>) 
with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the 
rules of the program's current locale (see setlocale(SC)). 

The members of the structure with type char * are strings, any of which (except decimal_point) can point 
to " " (the empty string) to indicate that the value is not available in the current locale or is of zero length. 
The members with type char are non-negative numbers, any of which can be CHAR_MAX (defined in 
<limlts .h>) to indicate that the value is not available in the current locale. The members include the 
following: 

char *decimal_point 

The decimal point character used to format non-monetary quantities. This is the same value as 
that returned by a call to nl_langinf o ( ) with RADIXCHAR as its argument (see 
nljanginfo (3 C)). 

char *thousands_sep 

The character used to separate groups of digits to the left of the decimal point character in for- 
matted non-monetary quantities. This is the same value as that returned by a call to 
nl_langinf o ( ) with THOUSEP as its argument (see nl_langinfo(3C)). 

char * grouping 

A string where the numeric value of each byte indicates the size of each group of digits in format- 
ted non-monetary quantities. 

char *lnt_curr_symbol 

The international currency symbol applicable to the current locale. The first three characters 
contain the alphabetic international currency symbol in accordance with those specified in ISO 
4217 Codes for the Representation of Currency and Funds. The fourth character (immediately 
preceding the null character) is the character used to separate the international currency symbol 
from the monetary quantity. 

char *currency_symbol 

The local currency symbol applicable to the current locale. This value along with positioning 
information is returned by a call to nl_langlnf o ( ) with CRNCYSTR as its argument (see 
nl_langinfo(3C)). 

char *mon_decimal_point 

The decimal point used to format monetary quantities. 

char *mon_thousands_sep 

The separator for groups of digits to the left of the decimal point in formatted monetary quanti- 
ties. 

char *mon_grouplng 

A string where the numeric value of each byte indicates the size of each group of digits in format- 
ted monetary quantities. 

char *posltive_sign 

The string used to indicate a non-negative-valued formatted monetary quantity. 

char *negatlve_sign 

The string used to indicate a negative-valued formatted monetary quantity. 

char lnt_f rac_digits 

The number of fractional digits (those to the right of the decimal point) to be displayed in an 
internationally formatted monetary quantity. 
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char frac_digits 

The number of fractional digits (those to the right of the decimal point) to be displayed in a 
locally formatted monetary quantity. 

char p_cs_precedes 

Set to 1 or if the cur rency_symbol respectively precedes or succeeds the value for a non- 
negative formatted monetary quantity. 

char p_sep_by_space 

Set to 1 or if the currency_symbol respectively is or is not separated by a space from the 
value for a non-negative formatted monetary quantity. 

char n cs, precedes 

Set to 1 or if the currency_symbol respectively precedes or succeeds the value for a nega- 
tive formatted monetary quantity. 

char n_sep_by_space 

Set to 1 or if the cur rency_symbol respectively is or is not separated by a space from the 
value for a negative formatted monetary quantity. 

char p_sign_posn 

Set to a value indicating the positioning of the positive_slgn for a non-negative formatted 
monetary quantity. 

char n_sign_posn 

Set to a value indicating the positioning of the negative_sign for a negative formatted 
monetary quantity. 

The numeric value of each byte of grouping and mon_grouping is interpreted according to the follow- 
ing: 

CHAR_MAX No further grouping is to be performed. 

The previous byte is to be repeatedly used for the remainder of the digits. 

other The value is the number of digits that comprise the current group. The next byte is 

examined to determine the size of the next group of digits to the left of the current 
group. 

The value of p_sign_posn and n_sign_posn is interpreted according to the following: 

Parentheses surround the quantity and currency_symbol. 

1 The sign string precedes the quantity and currency_symbol. 

2 The sign string succeeds the quantity and currency_symbol. 

3 The sign string immediately precedes the currency_symbol. 

4 The sign string immediately succeeds the currency_symbol. 

localeconv ( ) behaves as if no library function calls localeconv ( ) . 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category influences the decimal_polnt, thousands_sep, and grouping 
members of the structure referenced by the pointer returned from a call to localeconv ( ) . 

The LC_MONETARY category influences all of the other members of this structure. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

localeconv ( ) returns a pointer to the filled-in struct lconv. 

EXAMPLES 

The following table illustrates the formatting used in five languages for monetary quantities. 
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Country 


Positive format 


Negative format 


International format 


american 


$1,234.56 


-$1,234.56 


USD 1,234.56 


italian 


L. 1.234 


-L. 1.234 


ITL. 1.234 


dutch 


F 1.234,56 


F -1.234,56 


NLG 1.234,56 


norwegian 


krl.234,56 


krl.234,56- 


NOK 1.234,56 


Portuguese 


1,234$56 


-1,234$56 


PTE 1,234$56 



For these five languages, the respective values for the monetary members of the structure returned by 
localeconv ( ) are: 





amencan 


italian 


dutch 


norwegian 


Portuguese 


int_cur r_symbo 1 


USD 


ITL. 


NLG 


NOK 


PTE 


currency_symbol 


$ 


L. 


F 


kr 


$ 


mon_dec imal_point 


. 


.... 


, 


# 


$ 


mon_thous ands_s ep 


/ 


. 


. 


. 


, 


mon_grouping 


\3 


\3 


\3 


\3 


\3 


posit ive_sign 


II II 


.... 


.... 


.... 


.... 


negat ive_s ign 


- 


- 


- 


- 


- 


int_frac_digits 


2 





2 


2 


2 


f rac_digits 


2 





2 


2 


2 


p_cs_precedes 


1 


1 


1 


1 





P_s ep_by_spac e 








1 








n_cs_precedes 


1 


1 


1 


1 





n_s ep_by_spac e 








1 








p_sign_posn 


1 


1 


1 


1 


1 


n_sign_posn 


4 


1 


4 


2 


1 



WARNINGS 

The structure returned by localeconv ( ) should not be modified by the calling program. Calls to set- 
locale ( ) with categories LC_ALL, LC_MONETARY, or LC_NUMERIC can overwrite the contents of the 
structure that localeconv ( ) points to when it returns (see setlocale(3C)). 

AUTHOR 

localeconv ( ) was developed by HP. 

SEE ALSO 

buildlang(lM), langinfo(3C), nl_langinfo(3C), setlocale(3C), hpnls(5). 

STANDARDS CONFORMANCE 

localeconv ( ) : AES, XPG4, ANSI C 
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NAME 

logname() - return login name of user 

SYNOPSIS 

#include <unistd.h> 

char * logname ( vo id ) ; 

DESCRIPTION 

logname ( ) returns a pointer to the null-terminated login name; it extracts the $LOGNAME variable from 
the user's environment. 

WARNINGS 

logname ( ) returns a pointer to static data that is overwritten by each subsequent call. 

This method of determining a login name is subject to forgery. 

FILES 

/etc/profile 

SEE ALSO 

env(l), login(l), profile(4), environ(5). 

STANDARDS CONFORMANCE 

logname ( ) : SVID2, XPG2 
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NAME 

lsearch(), lfind() - linear search and update 

SYNOPSIS 

#include <search.h> 

void *lsearch( 

const void *key, 
void *base, 
size_t *nelp, 

5iZ6 u wiutu, 

int (*compar) (const void *, const void *) 
); 

void *lfind( 

const void *key, 

const void *base, 

size_t *nelp, 

size_t width, 

int (*compar) (const void *, const void *) 
); 

DESCRIPTION 

lsearch( ) is a linear search routine generalized from Knuth (6.1) Algorithm S. It returns a pointer 
into a table indicating where a datum may be found. If the datum does not occur, it is 
added at the end of the table. 

key Points to the datum to be sought in the table. 

base Points to the first element in the table. 

nelp Points to an integer containing the current number of elements in the 

table. The integer is incremented if the datum is added to the table. 

compar Name of the comparison function which the user must supply 

(strcmp ( ) , for example). It is called with two arguments that point 
to the elements being compared. The function must return zero if the 
elements are equal and non-zero otherwise. 

lfind() 

Same as lsearch ( ) except that if the datum is not found, it is not added to the table. Instead, a NULL 
pointer is returned. 

Notes 

The pointers to the key and the element at the base of the table should be of type pointer-to-element, and 
cast to type pointer-to -character. 

The comparison function need not compare every byte, so arbitrary data may be contained in the elements 
in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be cast into type pointer-to- 
element. 

EXAMPLES 

This code fragment reads in < TABSIZE strings of length < ELSIZE and stores them in a table, eliminat- 
ing duplicates. 

#include <stdio.h> 

ttdefine TABSIZE 50 
ttdefine ELSIZE 120 

char line [ELSIZE], tab [TABSIZE] [ELSIZE] , *lsearch( ) ; 
unsigned nel =0; 
int strcmp ( ); 
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while (f gets (line, ELSIZE, stdin) 1= NULL && 
nel < TABSIZE) 

(void) 1 search (line, (char *)tab, &nel, 
ELSIZE, strcmp); 

SEE ALSO 

bsearch(3C), hsearch(3C), tsearch(3C). 

RETURN VALUE 

If the searched-for datum is found, both lsearch() and lfind() return a pointer to it. Otherwise, 
If ind( ) returns NULL and lsearch ( ) returns a pointer to the newly added element. 

WARNINGS 

Undefined results can occur if there is not enough room in the table to add a new item. 

STANDARDS CONFORMANCE 

lsearch ( ) : AES, SVID2, XPG2, XPG3, XPG4 

If ind( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

ltostr(), ultostr(), ltoa(), ultoa() - convert long integers to strings 

SYNOPSIS 

ttinclude <stdlib.h> 

char *ltostr(long n, int base); 

char *ultostr (unsigned long n, int base); 

char *ltoa(long n) ; 

char *ultoa (unsigned long n) ; 

DESCRIPTION 

ltostr ( ) Convert a signed long integer to the corresponding string representation in the specified 
base. The argument base must be between 2 and 36, inclusive. 

ultostrO Convert an unsigned long integer to the corresponding string representation in the 
specified base. The argument base must be between 2 and 36, inclusive. 

ltoa ( ) Convert a signed long integer to the corresponding base 10 string representation, returning 

a pointer to the result. 

ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, 

returning a pointer to the result. 

These functions are smaller and faster than using spr intf ( ) for simple conversions (see sprintf(3C)). 

ERRORS 

If the value of base is not between 2 and 36, ltostr ( ) and ultostr ( ) return NULL and set the exter- 
nal variable errno to ERANGE. 

WARNINGS 

The return values point to static data whose content is overwritten by each call. 

AUTHOR 

ltostr (), ultostr (), ltoa (), and ultoa() were developed by HP. 

SEE ALSO 

printf(3C), strtol(3C). 
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NAME 

malloc(), free(), reallocO, calloc(), mallopt(), mallinfo(), memorymapO - main memory allocator 

SYNOPSIS 

ttinclude <stdlib.h> 

void *malloc(size_t size); 

void *calloc(size_t nelem, size_t elsize); 

void *realloc(void *ptr, size_t size); 

void free (void *ptr) ; 

void memo rymap( int show_stats) ; 

SYSTEM V SYNOPSIS 

#include <malloc.h> 

char *ma Hoc (unsigned size); 

void free (char *ptr) ; 

char *realloc(char *ptr, unsigned size); 

char *calloc (unsigned nelem, unsigned elsize); 

int mallopt(int cmd, int value); 

struct mallinfo mall info (void) ; 

Remarks 

The functionality in the old malloc(SX) package has been incorporated into malloc(3C). The library 
(/usr/lib/libmalloc.a) corresponding to the -lmalloc linker option is now an empty library. 
Makefiles that reference this library will continue to work. Applications that used the malloc(3X) package 
should still work properly with the new malloc(3C) package. If the old versions must be used, they are pro- 
vided infiles /usr/old/libmalloc3x.aand /usr/old/libmalloc3c.o for Release 8.07 only. 

DESCRIPTION 

The functions described in this manual entry provide a simple, general-purpose memory allocation package: 

ma Hoc ( ) allocates space for a block of at least size bytes, but does not initialize the space. 

calloc ( ) allocates space for an array of nelem elements, each of size elsize bytes, and initializes 
the space to zeros. 

real loc ( ) changes the size of the block pointed to by ptr to size bytes and returns a pointer to 
the (possibly moved) block. Existing contents are unchanged up to the lesser of the 
new and old sizes. If ptr is a NULL pointer, reallocO behaves like malloc() 
for the specified size. If size is zero and ptr is not a NULL pointer, the object it points 
to is freed and NULL is returned. 

free ( ) deallocates the space pointed to by ptr (a pointer to a block previously allocated by 

ma Hoc ( ) , realloc ( ) , or calloc ( ) ) and makes the space available for further 
allocation. If ptr is a NULL pointer, no action occurs. 

mallopt ( ) provides for control over the allocation algorithm and other options in the malloc(3C) 
package. The available values for cmd are: 

M_MXPAST Set maxfast to value. The algorithm allocates all blocks below 
the size of maxfast in large groups, then doles them out very 
quickly. The default value for maxfast is zero (0). 

M_NLBLKS Set numlblks to value. The above mentioned 'large groups" 
each contain numlblks blocks, numlblks must be greater than 
1. The default value for numlblks is 1 . 

M_GRAIN Set grain to value. The sizes of all blocks smaller than maxfast 

are considered to be rounded up to the nearest multiple of 
grain, grain must be greater than zero. The default value of 
grain is the smallest number of bytes that can accommodate 
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alignment of any data type, value is rounded up to a multiple of 
the default v/hen grain is set. 

M_KEEP Preserve data in a freed block until the nextmalloc ( ) , real- 

loc ( ) , or calloc ( ) . This option is provided only for compa- 
tibility with the old version of malloc () and is not recom- 
mended. 

M_BLOCK Block all blockable signals in malloc ( ) , realloc ( ) , cal- 

loc (), and free(). This option is provided for those who 
need to write signal handlers that allocate memory. When set, 
the malloc(3C) routines can be called from within signal 
handlers (they become re-entrant). Default action is not to 
block all blockable signals. 

M_UBLOCK Do not block all blockable signals in malloc ( ) , realloc ( ) , 
calloc ( ) , and free ( ) . This option cancels signal blocking 
initiated by the M_BLOCK option. 

These values are defined in the <3tialloc . h> header file. 

ma 11 opt ( ) can be called repeatedly, but must not be called after the first small block is allocated 
(unless cmd is set to M_BLOCK or M_UBLOCK). 

mallinfo() 
provides instrumentation describing space usage, but cannot be called until the first small block is allo- 
cated. It returns the structure: 

space in arena */ 
r of ordinary blocks */ 
r of small blocks */ 

in holding block headers */ 
r of holding blocks */ 
in small blocks in use */ 
in free small blocks */ 
in ordinary blocks in use */ 
in free ordinary blocks */ 
penalty if keep option is used */ 
} 
This structure is defined in the <malloc . h> header file. 

Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) 
for storage of any type of object. 

memorymap ( ) 

can be used to display the contents of the memory allocator. A list of addresses and 
block descriptions is written (using print f ( ) ) to standard output. If the value of 
the show_stats parameter is 1, statistics concerning number of blocks and sizes used 
will also be written. If the value is zero, only the memory map will be written. 

The addresses and sizes displayed by memorymap may not correspond to those 
requested by an application. The size of a block (as viewed by the allocator) includes 
header information and padding to properly align the block. The address is also 
offset by a certain amount to accomodate the header information. 

RETURN VALUE 

Upon successful completion, malloc ( ) , realloc ( ) , and calloc ( ) return a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL 
pointer. If realloc () returns a NULL pointer, the memory pointed to by the original pointer is left 
intact. 

mallopt ( ) returns zero for success and non-zero for failure. 



struct mall info { 






int arena; 


/* 


total 


int ordblks; 


/* 


numbe 


int smblks ; 


/* 


numbe 


int hblkhd; 


/* 


space 


int hblks; 


/* 


numbe 


int usmblks; 


/* 


space 


int f smblks; 


/* 


space 


int uordblks; 


/* 


space 


int f ordblks; 


/* 


space 


int keepcost; 


/* 


space 
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ERRORS 

[ENOMEM] malloc ( ) , realloc ( ) , and calloc ( ) set errno to ENOMEM and return a NULL 

pointer when an out-of -memory condition arises. 

[EINVAL] malloc (), realloc (), and calloc () set errno to EINVAL and return a NULL 

pointer when the memory being managed by malloc ( ) has been detectably corrupted. 

DIAGNOSTICS 

malloc (),realloc(), and calloc ( ) return a NULL pointer if there is no available memory, or if the 
memory managed by malloc ( ) has been detectably corrupted. This memory may become corrupted if 
data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by malloc () , 
realloc ( ) , or callocQ) is passed as an argument to free ( ) or realloc ( ) . 

If mallopt() is called after any allocation of a small block and cmd is not set to M_BLOCK or 
M_UBLOCK or if cmd or value is invalid, non-zero is returned. Otherwise, it returns zero. 

WARNINGS 

malloc functions use brk() and sbrk() (see brk (2)) to increase the address space of a process. There- 
fore, an application program that uses brk ( ) or sbrk ( ) must not use them to decrease the address 
space, because this confuses the malloc functions. 

free() and realloc () do not check their pointer argument for validity. 

If free ( ) or realloc ( ) is passed a pointer that was not the result of a call to malloc () , real- 
loc ( ) , or calloc ( ) , or if space assigned by an allocation function is overrun, loss of data, a memory 
fault, bus error, or an infinite loop may occur at that time or during any subsequent call to malloc ( ) , 
realloc ( ) , calloc ( ) , or free ( ) . 

The following actions are not supported and cause undesirable effects: 

• Attempting to free() or realloc () a pointer not generated as the result of a call to mal- 
loc ( ) , realloc ( ) , or calloc ( ) . 

The following actions are strongly discouraged and may be unsupported in a future implementation of 
malloc(ZC): 

• Attempting to free ( ) the same block twice. 

• Depending on unmodified contents of a block after it has been freed. 
Undocumented features of earlier memory allocators have not been duplicated. 

COMPATIBILITY 

The only external difference between the old malloc(SK) allocator and the malloc(SC) allocator is that the 
old allocator would return a NULL pointer for a request of zero bytes. The malloc(SC) allocator returns a 
valid memory address. This is not a concern for most applications. 

Although the current implementation of mallociZC) allows for freeing a block twice and does not corrupt the 
contents of a block after it is freed (until the next call to realloc (), calloc ( ), or malloc ( )), support 
for these features may be discontinued in a future implementation of malloc(3C) and should not be used. 

SEE ALSO 

brk(2), errno(2). 

STANDARDS CONFORMANCE 

malloc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 
calloc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 

free ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 
mall info ( ) : SVID2, XPG2 

mallopt ( ) : SVID2, XPG2 

realloc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, P0SIX.1, ANSI C 
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NAME 

matherr() - error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (struct exception *x) 
{ 

/* your math error handling here */ 
} 

DESCRIPTION 

matherr ( ) is invoked by functions in the Math Library when errors are detected. Programmers can 
define their own procedures for handling errors by including a function named matherr ( ) in their pro- 
grams, matherr ( ) must be of the form described above. When an error occurs, a pointer to the excep- 
tion structure x is passed to the user-supplied matherr ( ) function. This structure, which is denned in 
the <math . h> header file, is as follows: 

struct exception { 

int type; 

char *name; 

double argl, arg2, retval; 
}; 

The element type is an integer describing the type of error that has occurred, from the following list of 
constants (defined in the header file): 

DOMAIN argument domain error 

SING argument singularity 

OVERFLOW overflow range error 

UNDERFLOW underflow range error 

TLOSS total loss of significance 

P LO S S partial lo ss of significance 

The element name points to a string containing the name of the function that incurred the error. The 
variables argl and arg2 are the arguments with which the function was invoked, retval is set to 
the default value that will be returned by the function unless the user's matherr ( ) sets it to a different 
value. If there is only one argument, argl is set to it, and arg2 is undefined. 

If the user's matherr () function returns non-zero, no error message is printed, and errno is not set. 

If matherr ( ) is not supplied by the user, the default error-handling procedures (described with the math 
functions involved) are invoked upon error. These procedures are also summarized in the table below. In 
every case, errno is set to EDOM or ERANGE and the program continues. 

When matherr ( ) is called from a float type math function (for example, expf ( ) or logf ( ) ), the 
argument(s) and default return value (argl, arg2, and retval) are converted to double. If an argu- 
ment is a NaN, it is converted to a double NaN, without trapping, even if it is a signaling NaN. If a 
user-supplied matherr () function modifies retval, the value is converted to float when math- 
err () returns. If that conversion fails, then a signal is generated. Therefore, it is the responsibility of the 
user-supplied matherr ( ) to select values for retval that can be successfully converted to float. 

DEPENDENCIES 
/lib/libM.a 

In /lib/libM.a, matherr () has been renamed to _matherr() and no error messages are printed 
to the standard error output. _matherr ( ) is provided in /lib/libM.a in order to assist in migrat- 
ing programs from 1 ibm . a to 1 ibM . a and is not a part of XPG3, ANSI C, or POSDC. 

EXAMPLES 

# include <math.h> 

int 

matherr (x) 

register struct exception *x; 

{ 

switch (x->type) { 
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} 



DEFAULTS 



case DOMAIN: 

/* change sqrt to return sqrt(-argl), not */ 
if ( !strcmp(x->name, "sqrt")) { 

x->retval = sqrt (-x->argl) ; 

return (0); /* print message and set errno */ 
> jj= ( 

else xf (; StiCiup (X- > name , l! Sqi tf " ) ) { 

x- >r et val = sqrt f ( -x- >ar gl ) ; 

return (0); /* print message and set errno */ 
} 
case SING: 

/* all other domain or sing errors, print message and abort */ 

£_-_.■ — 4- -c i _4-.a~.-~>— iu_ — — J — _____ j— o>, _ \ _ it „ ^____\ . 
L^iiuui, v o uuei i. / uuuiai.il esj. -lv-ij. j.u 'oo \i- / X— ^-ixcuuc: y / 

abort ( ) ; 
case PLOSS: 

/* print detailed error message */ 

fprintf (stderr, "loss of significance in %s(%g) = %g\n", 
x->name, x->argl, x->retval); 

return (1); /* take no other action */ 
} 
return (0); /* all other errors, execute default procedure */ 



DEFAULT ERROR HANDLING PROCEDURES 




Types of Errors 


type 


DOMAIN 


SING 


OVERFLOW 


UNDERFLOW 


TLOSS 


PLOSS 


errno 


EDOM 


EDOM 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 

y0, yl, yn (arg <= 0) 


M,-H 


- 


- 


- 


M,0 


* 


EXP: 


- 


- 


H 





- 


- 


LOG, LOG10: 
(arg < 0) 
(arg = 0) 


M,-H 


M,-H 


- 


- 


- 


- 


POW: 

neg ** non-int 
** non-pos 


M,0 


■ 


±H 





- 


- 


SQRT: 


M,0 


- 


- 


- 


- 


- 


GAMMA: 


- 


M,H 


H 


- 


- 


- 


HYPOT: 


- 


- 


H 


- 


- 


- 


SINH: 


- 


- 


±H 


- 


- 


- 


COSH: 


- 


- 


H 


- 


- 


- 


SIN, COS, TAN: 


- 


- 


- 


- 


M,0 


* 


ASIN, ACOS, ATAN2: 


M,0 


- 


- 


- 


- 


- 





ABBREVIATIONS 


* 


As much as possible of the value is returned. 


M 


Message is printed (EDOM error) 




(except for Series 700/800 libM.a). 


H 


HUGE is returned. 


-H 


-HUGE is returned. 


±H 


HUGE or -HUGE is returned. 





is returned. 



STANDARDS CONFORMANCE 

matherr ( ) in libm.a: SVID2, XPG2, XPG3 
matherr ( ) in libM.a: XPG3 
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NAME 

memccpyO, memchr(), memcmpO, memcpyO, memmove(), memset(), bcopyO, bcmp(), bzero(), ffs() - 
memory operations 

SYNOPSIS 

#include <string.h> 

void *memccpy(void *sl, const void *s2, int c, size_t n) ; 

void *memchr (const void *s, int c, size_t n) ; 

int memcmp (const void *sl / const void *s2/ size t n) * 

void *memcpy (void *sl, const void *s2, size_t n) ; 

void *meinmove (void *sl, const void *s2, size_t n) ; 

void *memset (void *s, int c, size_t n) ; 

#include <strings.h> 

int bcmp(const char *sl, const char *s2, int n) ; 

void bcopy(const char *sl, char *s2, int n) ; 

void bzero(char *s, int n) ; 

int ffs(int i); 

Remarks: 

bcmp ( ) , bcopy ( ) , bzero ( ) , f f s ( ) , and <strings . h> are provided solely for portability of BSD 
applications, and are not recommended for new applications where portability is important. For portable 
applications, use memcmpO, memmove (), and memsetO, respectively. ffs() has no portable 
equivalent. 

DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays of characters bounded by a 
count, not terminated by a null character). They do not check for the overflow of any receiving memory 
area. 

Definitions for all these functions, the type size_t, and the constant NULL are provided in the 
<string.h> header file. 

memccpy ( ) Copy characters from the object pointed to by s2 into the object pointed to by si , stopping 
after the first occurrence of character c has been copied, or after n characters have been 
copied, whichever comes first. If copying takes place between objects that overlap, the 
behavior is undefined, memccpy ( ) returns a pointer to the character after the copy of c 
in si, or a NULL pointer if c was not found in the first n characters of s2. 

memchr ( ) Locate the first occurrence of c (converted to an uns igned char) in the initial n charac- 
ters (each interpreted as unsigned char) of the object pointed to by s. memchr ( ) 
returns a pointer to the located character, or a NULL pointer if the character does not occur 
in the object. 

memcmp ( ) Compare the first n characters of the object pointed to by si to the first n characters of the 
object pointed to by s2. memcmp ( ) returns an integer greater than, equal to, or less than 
zero, according to whether the object pointed to by si is greater than, equal to, or less than 
the object pointed to by s2. The sign of a non-zero return value is determined by the sign of 
the difference between the values of the first pair of characters (both interpreted as 
unsigned char) that differ in the objects being compared. 

memcpy ( ) Copy n characters from the object pointed to by s2 into the object pointed to by si . If copy- 
ing takes place between objects that overlap, the behavior is undefined, memcpy ( ) 
returns the value of si . 

memmove ( ) Copy n characters from the object pointed to by s2 into the object pointed to by si . Copying 
takes place as if the n characters from the object pointed to by s2 are first copied into a tem- 
porary array of n characters that does not overlap the objects pointed to by si and s2, and 
then the n characters from the temporary array are copied into the object pointed to by si . 
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memmove ( ) returns the value of si . 

memset ( ) Copy the value of c (converted to an uns igned char) into each of the first n bytes of the 
object pointed to by s. memset ( ) returns the value of s. 

bcopy ( ) copies n bytes from the area pointed to by si to the area pointed to by s2 . 

bcmp ( ) Compare the first n bytes of the area pointed to by si with the area pointed to by s2. 

bcopy ( ) returns zero if they are identical; non-zero otherwise. Both areas are assumed to 
be n bytes in length. 

bzero ( ) Clear n bytes in the area pointed to by s by setting them to zero. 

f f s ( ) Find the first bit set (beginning with the least significant bit) and return the index of that 

bit. Bits are numbered starting at one. A return value of indicates that i is zero. 

International Code Set Support 

These functions support only single-byte character code sets. 

WARNING 

The functions defined in <st ring . h> were previously defined in -anemory . h>. 

SEE ALSO 

string(3C) 

STANDARDS CONFORMANCE 

memccpy ( ) : AES, SVID2, XPG2, XPG3, XPG4 
memchr ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 

memcmp ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 
memcpy ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 

memmove ( ) : AES, XPG4, ANSI C 

memset ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 



614 



-2- 



HP-UX Release 9.0: August 1992 



mkfifo(3C) mkfifo(3C) 



NAME 

mkfifoO - make a FIFO file 

SYNOPSIS 

#inc lude < sy s / st at . h> 

int mkf if o (char *path, mode_t mode); 

DESCRIPTION 

mkf if o ( ) creates a new FIFO (first-in-first-out) file, at the path name to which path points. The file per- 
mission bits of the new file are initialized from the mode argument, as modified by the process's file creation 
mask: for each bit set in the process's file mode creation mask, the corresponding bit in the new file's mode 
is cleared (see umask(2)). Bits in mode other than the file permission bits are ignored. 

The FIFO owner ID is set to the process's effective-user-ID. The FIFO group ID is set to the group ID of the 
parent directory if the set-group-ID bit is set on that directory. Otherwise the FIFO group ID is set to the 
process's effective group ID. 

For details of the I/O behavior of pipes see read(2) and write(2). 

The following symbolic constants are defined in the <sys/stat .h> header, and should be used to con- 
struct the value of the mode argument. The value passed should be the bitwise inclusive OR of the desired 
permissions: 

S_IRUSR Read by owner. 

S_IWUSR Write by owner. 

S_IRGRP Read by group. 

S_IWGRP Write by group. 

S_IROTH Read by other users. 

S_IWOTH Write by other users. 

RETURN VALUE 

mkf if o ( ) returns upon successful completion. Otherwise, it returns -1, no FIFO is created, and errno 
is set to indicate the error. 

ERRORS 

mkf if o ( ) fails and the new file is not created if any of the following conditions are encountered: 

[EACCES] A component of the path prefix denies search permission. 

[EEXIST] The named file already exists. 

[EFAULT] The path argument points outside the process's allocated address space. The reliable 

detection of this error is implementation dependent. 

[ELOOP] Too many symbolic links encountered in translating the path name. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the pathname exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENOENT] A component of the path prefix does not exist. 

[ENOENT] The path argument is null. 

[ENOSPC] Not enough space on the file system. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EROFS] The directory in which the file is being created is located in a read-only file system. 

SEE ALSO 

chmod(2), mknod(2), pipe(2), stat(2), umask(2), cdf(4), fs(4), mknod(5), stat(5), types(5). 

AUTHOR 

mkf if o ( ) was developed by HP. 

STANDARDS CONFORMANCE 

mkf if o ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.1 
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NAME 

mktempO, mkstempO - make a unique file name 

SYNOPSIS 

#include <unistd.h> 

char *mktemp(char * tempi ate) ; 
int mkstemp(char *template); 

Remarks: 

These functions are provided solely for backward compatibility and importability of applications, and are 
not recommended for new applications where portability is important. For portable applications, use 
tmpf lie ( ) instead (see tmpfile(3S)). 

DESCRIPTION 

mktemp ( ) replaces the contents of the string pointed to by template by a unique file name, and returns the 
address of template. The string in template should look like a file name with six trailing Xs; mktemp ( ) 
replaces the Xs with a letter and the current process ID. The letter is chosen such that the resulting name 
does not duplicate the name of an existing file. If there are fewer than six Xs, the letter is dropped first, fol- 
lowed by dropping the high-order digits of the process ID. 

mkstemp( ) makes the same replacement to the template, but also returns a file descriptor for the tem- 
plate file after opening the file for reading and writing, mkstemp ( ) thus prevents any possible race con- 
dition between testing whether the file exists and opening it for use. 

RETURN VALUE 

mktemp ( ) returns its argument except when it runs out of letters, in which case the result is a pointer to 
the empty string " " . 

mkstemp ( ) returns an open file descriptor upon successful completion, or -1 if no suitable file could be 
created. 

SEE ALSO 

getpid(2), open(2), tmpfile(3S), tmpnam(3S). 

WARNINGS 

It is possible to run out of letters. 

mktemp ( ) and mkstemp ( ) do not check to determine whether the file name part of template exceeds the 
maximum allowable file name length. 

STANDARDS CONFORMANCE 

mktemp ( ) : SVID2, XPG2 
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NAME 

mktimer - allocate a per-process timer 

SYNOPSIS 

#include <sys/timers.h> 

timer_t mktimer (int clock_type, int notify_type, void *itimercbp); 

DESCRIPTION 

mktimer ( ) is used to allocate a per-process timer using the specified system-wide clock as the timing 
base, mktimer ( ) returns an unique timer ID of type timer J used to idnetify the timer in timer requests 
(see gettimer(3C)). clockjype specifies the system-wide clock to be used as the timing base for the new 
timer, nofityjype specifies the mechanism by which the process is to be notified when the timer expires. 

mktimer () supports one per-process timer with a clockjype of TIMEOPDAY and notify Jype of 
DELIVERY_S IGNALS. 

If notify Jype is DELIVERY_SIGNALS, the system causes a SIGALRM signal to be sent to the process 
whenever the timer expires. 

For clockjype TIMEOPDAY, the machine-dependent clock resolution and maximum value are 1/HZ and 
MAX_ALARM seconds respectively. These constants are defined in <sys /param . h>. 

RETURN VALUE 

Upon successful completion, mktimer () returns a timer_t which can be passed to the per_process 
timer calls. If unsuccessful, mktimer () returns a value of (time r_t)-l and sets errno to indicate 
the error. 

ERRORS 

mktimer ( ) fails if any of the following conditions are encountered: 

[EAGAIN] The calling process has already allocated all of the timers it is allowed. 
[EINVAL] clockjype is not defined, or does not allow the specified notification mechanism. 

SEE ALSO 

getclock(3C), gettimer(3C), reltimer(3C), rmtimer(3C), setclock(3C), <sys/timers.h>, <sys/param.h>. 

STANDARDS CONFORMANCE 

mktimer():AES 



HP-UX Release 9.0: August 1992 - 1 - 617 



monitor (3C) monitor (3C) 



NAME 

monitor() - prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor ( 

void (*lowpe)(), 

void (*highpc) (), 

WORD *buffer, 

int bufsize, 

int nfunc 
); 

DESCRIPTION 

An executable program created by cc -p automatically includes calls for monitor () with default 
parameters; monitor ( ) need not be called explicitly except to gain fine control over profiling. 

monitor ( ) is an interface to profil{2). lowpc and highpc are the addresses of two functions; buffer is the 
address of a (user-supplied) array of bufsize WORDs (denned in the <mon.h> header file), monitor ( ) 
arranges to record in the buffer a histogram of periodically sampled values of the program counter, and of 
counts of calls of certain functions. The lowest address sampled is that of lowpc and the highest is just 
below highpc. lowpc must not equal for this use of monitor. Not more than nfunc call counts can be kept; 
only calls of functions compiled with the profiling option -p of cc(l) are recorded. (The C Library and Math 
Library supplied when cc -p is used also have call counts recorded.) 

For results to be significant, especially where there are small, heavily used routines, it is suggested that the 
buffer be no more than a few times smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use 

extern etext; 

monitor ((int (*)())2, ((int(*)())& etext, buf, bufsize, nfunc); 
etext lies just above all the program text (see end(3C)). 
To stop execution monitoring and write the results on file mon. out, use 

monitor ((int (*)())0, (int(*)())0, 0, 0, 0); 
prof(l) can then be used to examine the results. 

FILES 

/lib/libp/libc.a 
/lib/libp/libm.a 
mon . out 

SEE ALSO 

cc(l), prof(l), profil(2), end(3C). 

STANDARDS CONFORMANCE 

monitor ( ) : SVID2, XPG2 
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NAME 

mount() - keep track of remotely mounted filesystems 

SYNOPSIS 

ttinclude < rpcsvc /mount .h> 

DESCRIPTION 

program number: 

MOUNTPROG 

Following are the xdr routines provided: 
xdr_exportbody(xdrs, ex) 

XDR *xdrs; 

struct exports *ex; 
xdr_exports(xdrs, ex); 

XDR *xdrs; 

struct exports **ex; 
xdr_fhandle(xdrs, fh); 

XDR *xdrs; 

fhandle_t *fp; 
xdr_fhstatus(xdrs, fhs); 

XDR *xdrs; 

struct fhstatus *fhs; 
xdr_groups(xdrs, gr); 

XDR *xdrs; 

struct groups *gr; 
xdr_mountbody(xdrs, ml) 

XDR *xdrs; 

struct mountlist *ml; 
xdr_mountlist(xdrs, ml); 

XDR *xdrs; 

struct mountlist **ml; 
xdr_path(xdrs, path); 

XDR *xdrs; 

char **path; 

procs: 

MOUNTPROC_MNT 

argument of xdr_path, returns fhstatus. 

Requires unix authentication. 
MOUNTPROCJDUMP 

no args, returns struct mountlist 
MOUNTPROCJJMNT 

argument of xdr_path, no results. 

requires unix authentication. 
MOUNTPROCJJMNTALL 

no arguments, no results. 

requires unix authentication. 

umounts all remote mounts of sender. 
MOUNTPROCJEXPORT 
MOUNTPROC.EXPORTALL 

no args, returns struct exports 

versions: 

MOUNTVERS ORIG 



structures: 

struct mountlist { 

char *ml_name; 

char *ml_path; 

struct mountlist *ml_nxt; 
}; 



/* what is mounted */ 
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struct fhstatus { 

int fhs_status; 
fliandle_t fhs_fh; 

}; 
/* 

* List of exported directories 

* An export entry with ex_groups 

* NULL indicates an entry which is exported to the 

* world. 
*/ 

struct exports { 

dev_t ex_dev; /* dev of directory */ 

char *ex_name; I* name of directory */ 

struct groups *ex_groups; /* groups allowed to */ 

/* mount this entry */ 
struct exports *ex_next; 

}; 

struct groups { 

char *g_name; 

struct groups *g_next; 
}; 

AUTHOR 

mount ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

mount(lM), mountd(lM), showmount(lM). 
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NAME 

mblenQ, mbtowc(), mbstowcsO, wctombO, wcstombs() - multibyte characters and strings conversions 

SYNOPSIS 

#include <stdlib.h> 

int mblen(const char *s, size_t n) ; 

int mbtowc (wchar_t *pwc, const char *s, size_t n) ; 

int wctomb (char *s, wchar_t wchar) ; 

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n) ; 

size_t wcs tombs (char *s, const wchar_t *pwcs, size_t n) ; 

DESCRIPTION 

A multibyte character is composed of one or more bytes that represent a "whole" character in a character 
encoding. A wide character (type of wchar_t) is composed of a fixed number of bytes whose code value can 
represent any character in a character encoding. 

mblen ( ) Determine the number of bytes in the multibyte character pointed to by s. Equivalent to: 

mbtowc ( (wchar_t *)0, s, n) ; 

If s is a null pointer, mblen returns a nonzero or zero value, depending on whether the multi- 
byte character encodings do or do not have state-dependent encodings, respectively. Since no 
character encodings currently supported by HP-UX are state-dependent, zero is always 
returned in this case. However, for maximum portability to other systems, application pro- 
grams should not depend on this. 

If s is not a null pointer, mblen returns the number of bytes in the multibyte character if the 
next n or fewer bytes form a valid multibyte character, or return -1 if they do not form a valid 
multibyte character. If s points to the null character, mblen returns 0. 

mbtowc ( ) Determine the number of bytes in the multibyte character pointed to by s, determine the code 
for the value of type wchar_t corresponding to that multibyte character, then store the code 
in the object pointed to by pwc. The value of the code corresponding to the null character is 
zero. At most n characters are examined, starting at the character pointed to by s. 

If s is a null pointer, mbtowc ( ) returns a non-zero or zero value, depending on whether the 
multibyte character encodings do or do not have state-dependent encodings, respectively. 
Since no character encodings currently supported by HP-UX are state-dependent, zero is always 
returned in this case. However, for maximum portability to other systems, application pro- 
grams should not depend on this. 

If s is not a null pointer, mbtowc ( ) returns the number of bytes in the converted multibyte 
character if the next n or fewer bytes form a valid multibyte character, or -1 if they do not form 
a valid multibyte character. If s points to the null character, mbtowc ( ) returns 0. The 
value returned is never greater than n or the value of the MB_CUR_MAX macro. 

wctomb ( ) Determine the number of bytes needed to represent the multibyte character corresponding to 
the code whose value is wchar and store the multibyte character representation in the array 
object pointed to by s. At most MB_CUR_MAX characters are stored. 

If s is a null pointer, wctomb ( ) returns a nonzero or zero value, depending on whether the 
multibyte character encodings do or do not have state-dependent encodings, respectively. 
Since no character encodings currently supported by HP-UX are state-dependent, zero is always 
returned in this case. However, for maximum portability to other systems, application pro- 
grams should not depend on this. 

If s is not a null pointer, wctomb ( ) returns the number of bytes in the multibyte character 
corresponding to the value of wchar, or -1 if the value of wchar does not correspond to a valid 
multibyte character. The value returned is never greater than the value of the MB_CUR_MAX 
macro. 

mbstowcs ( ) 

Convert a sequence of multibyte characters from the array pointed to by s into a sequence of 
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corresponding codes and store these codes into the array pointed to by pwcs, stopping after 
either n codes or a code with value zero (a converted null character) is stored. Each multibyte 
character is converted as if by a call to mbtowc ( ) . No more than n elements are modified in 
the array pointed to by pwcs. 

If an invalid multibyte character is encountered, mbstowcs() returns (size_t)-l. Other- 
wise, mbstowcs ( ) returns the number of array elements modified, not including a terminat- 
ing zero code, if any. The array is not null- or zero-terminated if the value returned is n. If 
pwcs is a null pointer, mbstowcs ( ) returns the number of elements required for the wide- 
character-code array. 

wcstombs () 

Convert a sequence of codes corresponding to multibyte characters from the array pointed to 
by pwcs into a sequence of multibyte characters and store them into the array pointed to by s, 
stopping if a multibyte character exceeds the limit of n total bytes or if a null character is 
stored. Each code is converted as if by a call to wctomb ( ) . No more than n bytes are 
modified in the array pointed to by s. 

If a code is encountered that does not correspond to a valid multibyte character, 
wcstombs () returns (size_t)-l. Otherwise, wcstombs ( ) returns the number of bytes 
modified, not including a terminating null character, if any. The array is not null- or zero- 
terminated if the value returned is n. If s is a null pointer, wcstombs () returns the 
number of bytes required for the character array. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the behavior of the multibyte character and string functions. 

ERRORS 

mblen( ), mbstowcs (), mbtowc (), wcstombs () and wctomb () may fail and errno is set if the 
following condition is encountered: 

[EILSEQ] An invalid multibyte sequence or wide character code was found. 

WARNINGS 

With the exception of ASCII characters, the code values of wide characters (type of wchar_t) are specific to 
the effective locale specified by the LC_CTYPE environment variable. These values may not be compatible 
with values obtained by specifying other locales that are supported now, or which may be supported in the 
future. It is recommended that wide character constants and wide string literals (see the C Reference 
Manual) not be used, and that wide character code values not be stored in files or devices because future 
standards may dictate changes in the code value assignments of the wide characters. However, wide char- 
acter constants and wide string literals corresponding to the characters of the ASCII code set can be safely 
used since their values are guaranteed to be the same as their ASCII code set values. 

AUTHOR 

The multibyte functions in this entry were developed by HP. 

SEE ALSO 

setlocale(3C), nl_tools_16(3C), wctype(3X). 

STANDARDS CONFORMANCE 

mblen ( ) : AES, XPG4, ANSI C 
mbstowcs (): AES, XPG4, ANSI C 

mbtowc ( ) : AES, XPG4, ANSI C 
wcstombs ( ) : AES, XPG4, ANSI C 

wctomb ( ) : AES, XPG4, ANSI C 
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NAME 

dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, 
dbm_clearerr - database subroutines 

SYNOPSIS 

#include <ndbm.h> 

DBM *dbm_open( const char *f lie, int flags, int mode) ; 

void dbm_c lose (DBM *db) ; 

datum dbm_feteh(DBM *db, datum key); 

int dbm_store(DBM *db, datum key, datum content, int flags); 

int dbm_delete(DBM *db, datum key); 

datum dbm_firstkey(DBM *db); 

datum dbm_nextkey(DBM *db) ; 

int dbm_error (DBM *db) ; 

int dbm__clearerr (DBM *db); 

DESCRIPTION 

These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 
1024 bytes)) databases and can access a keyed item in one or two file system accesses. This package 
replaces the earlier dbm(SX) library, which managed only a single database. The functions can be accessed 
by giving the - lndbm option to ld(l) or cc(l). 

key and content parameters are described by the datum type. A datum specifies a string of dsize bytes 
pointed to by dptr. Arbitrary binary data, as well as normal ASCII strings, are allowed. The database is 
stored in two files. One file is a directory containing a bit map of keys and has .dir as its suffix. The 
second file contains all data and has . pag as its suffix. 

Before a database can be accessed, it must be opened by dbm_open. This will open and/or create the files 
file . dir and file . pag depending on the flags parameter (see open(2)). 

Once open, the data stored under a key is accessed by dbm_f etch and data is placed under a key by 
dbm_store. The flags field can be either DBM_INSERT or DBM_REPLACE. DBM_INSERT can only 
insert new entries into the database, and cannot change an existing entry having the same key. 
DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is 
deleted by dbm_delete. A linear pass through all keys in a database can be made in (apparently) ran- 
dom order by use of dbm_f ir stkey and dbm_nextkey. dbm_f ir s t key returns the first key in the 
database. dbm_nextkey returns the next key in the database, The following code can be used to 
traverse the database: 

for (key = dbm_f irstkey (db) ; key. dptr != NULL; key = dbm_nextkey (db) ) 

dbm_error returns non-zero when an error has occurred reading or writing the database. 
dbm_clearerr resets the error condition on the named database. 

DIAGNOSTICS 

All functions that return an int indicate errors with negative values and success with zero. Functions 
that return a datum indicate errors with a null dptr. If dbm_store is called with a flags value of 
DBM_INSERT and finds an existing entry with the same key, a value of 1 is returned. 

WARNINGS 

The ndbm functions provided in this library should not be confused in any way with those of a general- 
purpose database management system such as ALLBASE/HP-UX SQL. These functions do not provide for 
multiple search keys per entry, they do not protect against multi-user access (in other words they do not 
lock records or files), and they do not provide the many other useful database functions that are found in 
more robust database management systems. Creating and updating databases by use of these functions is 
relatively slow because of data copies that occur upon hash collisions. These functions are useful for appli- 
cations requiring fast lookup of relatively static information that is to be indexed by a single key. 

The . pag file will contain holes so that its apparent size is about four times its actual content. Some older 
UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal 
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means (such as cp(l), cat(l), tar(l), or ar(l)) without expansion. 

dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. 

The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). 
Moreover, all key/content pairs that hash together must fit on a single block. dbm_store returns an 
error in the event that a disk block fills with inseparable data. 

dbKi_delete does not physically reclaim file space, although it does make it available for reuse. 

The order of keys presented by dbm_f irstkey and dbm_nextkey depends on a hashing function, not 
on anything interesting. 

A dbm_store or dbm_delete during a pass through the keys by dbm_f irstkey and 
dbm_nextkey may yield unexpected results. 

AUTHOR 

ndbm(3X) was developed by the University of California, Berkeley. 

SEE ALSO 

dbm(3X). 
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NAME 

net_aton(), net_ntoa() - network station address string conversion routines 

SYNOPSIS 

#include <sys/netio.h> 

char *net_aton(char *dstr, const char *sstr, int size); 
char *net_ntoa(char *dstr, const char *sstr, int size); 

DESCRIPTION 

net_aton{ ) and net_ntoa ( ) translate station addresses between hexadecimal, octal or decimal, and 
binary formats: 

net_at on ( ) converts a hexadecimal, octal or decimal address to a binary address; 

net_ntoa ( ) converts a binary address to an ASCII hexadecimal address. 

Both routines are provided in the standard C library and are loaded automatically during compilation. 

net_aton Parameter's 

The following parameters are used by net_aton ( ) : 

dstr Pointer to the binary address returned by the function. 

sstr Pointer to a null-terminated ASCII form of a station address (Ethernet or IEEE 802.3). This 

address can be an octal, decimal, or hexadecimal number as used in the C language (in 
other words, a leading Ox or OX implies hexadecimal; a leading implies octal; otherwise, 
the number is interpreted as decimal). 

size Length of the binary address to be returned in dstr. The length is 6 for Ethernet/IEEE 802.3 

addresses. _ 

netjntoa Parameters | 

net_ntoa ( ) converts a 48-bit binary station address to its ASCII hexadecimal equivalent. The following 
parameters are used by net_nt oa ( ) : 

dstr Pointer to the ASCII hexadecimal address returned by the function, dstr is null-terminated 

and padded with leading zeroes if necessary, dstr must be at least (2 x size + 3) bytes long 
to accommodate the size of the converted address. 

sstr Pointer to a station address in its binary form. 

size Length of sstr. 

RETURN VALUE 

net_aton() and net_ntoa() return NULL if any error occurs. 

EXAMPLES 

#include <netio.h> 

#define destination_addr "0x00DD0002AD00" 

struct fis arg; 
char str [16] ; 

(void) net_aton(arg.value.s, destination_addr, 6); 

/* arg. value. s = "<48-bit binary value>" */ 
(void) net_ntoa(str, arg. value. s, 6); 

/* str = "0X00DD0002AD00" */ 

AUTHOR 

net_aton ( ) was developed by HP. 

SEE ALSO 

lan(7). 
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NAME 

nl_toupper(), nl_tolower() - translate characters for use with NLS 

SYNOPSIS 

#include <nl_ctype.h> 

int nl_toupper (int c, int langid) ; 
int nl_tolower (int c, int langid); 

DESCRIPTION 

nl_toupper() and nl_tolower() are extensions of their counterparts in the conv (3 C) manual entry. 
They function in the same way, but have a langid parameter (see lang(5)) whose value represents a sup- 
ported language. If langid is not valid, or if the NLS environment corresponding to langid is not available, 
n-computer, the default NLS environment associated with langinit ( ) , is used (see nl_init(SC)). 

WARNINGS 

These routines are provided for historical reasons only. Use of the alternate functions listed by conv(3C) 
which provide for international support via setlocale(3C) is recommended. 

nl_toupper() and nl_tolower() effectively call langinit () to load the NLS environment 
according to the language specified by langid. 

AUTHOR 

nl_conv ( ) was developed by the HP. 

SEE ALSO 

conv(3C), nl_init(3C), hpnls(5), lang(5). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the translations to be done. 

International Code Set Support 

Single-byte character code sets are supported. 
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NAME 

nl_isalpha(), nl_isupper(), nl_islower(), nl_isdigit(), nl_isxdigit(), nljsalnum(), nl_isspace( ), nl_ispunct(), 
nl_isprint(), nl_isgraph( ), nl_iscntrl() - classify characters for use with NLS 

SYNOPSIS 

#include <nl_ctype.h> 

int nl_isalpha(int c, int langid) ; 

DESCRIPTION 

These routines classify character-coded integer values by table lookup, langid corresponds to a particular 
NLS environment (see lang(5)). Each is a predicate returning nonzero for true, zero for false. All are 
defined for the range -1 to 255. If langid is not defined, or if the NLS environment corresponding to langid 
is not available, n-computer, the default NLS environment associated with langinit ( ), is used (see 
nl_init(3C)). 

nl_i s a lpha ( ) c is a letter. 

nl_i supper ( ) c is an uppercase letter. 

nl_i s 1 ower ( ) c is a lowercase letter. 

nl_i sdigit ( ) c is a decimal digit (in ASCII: characters [0-9]). 

nl_isxdigit ( ) c is a hexadecimal digit (in ASCII: characters [0-9], [A-F] or [a-f]). 

nl_i salnum ( ) c is an alphanumeric (letters or digits). 

nl_i s space ( ) c is a character that creates "white space" in displayed text (in ASCII: space, tab, 
carriage return, new-line, vertical tab, and form-feed). 

nl_ispunct ( ) c is a punctuation character (in ASCII: any printing character except the space 
character (040), digits, letters.) 

nl_i sprint ( ) c is a printing character. 

nl_is graph ( ) c is a visible character (in ASCII: printing characters, excluding the space char- 
acter (040)). 

nl_iscntrl ( ) c is a control character (in ASCII: character codes less than 040 and the delete 
character (0177)). 

DIAGNOSTICS 

If the argument to any of these is not in the domain of the function, the result is undefined. 

WARNINGS 

These macros are provided for historical reasons only. Use of the macros in ctype($C), which now provide 
for international support via setlocale(SC), is recommended. 

Macros described in this manual entry call langinit ( ) to load the NLS environment according to the 
language specified by langid. 

AUTHOR 

nl_ctype ( ) was developed by the HP. 

SEE ALSO 

ctype(3C), nl_init(3C), hpnls(5), lang(5). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the classification of character type. 

International Code Set Support 

Single-byte character code sets are supported. 
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NAME 

nl_init(), langinit() - initialize the NLS environment of a program 

SYNOPSIS 

#lnclude <langlnfo.h> 

int nl_init (const char *langname); 
int langinit (const char *langname) ; 

DESCRIPTION 

nl_init ( ) Initializes the NLS (Native Language Support) environment of a program to the 

language specified by langname. If langname is null or points to an empty string, the 
default-mode language, n- computer (see lang(5)), is initialized. 

nl_init ( ) affects the behavior of the macros and routines denned in conv(3C), 
ctime(3C), ctype(3C), ecvt(3C), langinfo(3C), multibyte(3C), nl_langinfo(3C), 
nl_string(3C), nl_tools_16(3C), printf(3S\ printmsg(3C), scanf(3S), strftime(3C), 
string(3C\ strtod(3C), and vprintf(3S). 

Typically, nl_init ( ) is used to bind program operation to the end-user's specified 
language requirements. For example, 

nl_init(getenv("LANG") ) ; 

Prior to successfully calling nl_init ( ), functions supporting NLS operate as though the default-mode 
language n- computer had been initialized. 

langinit () 

Performs the same initialization of the environment control areas as does nl_init ( ) . However, 
nl_init ( ) and langinit ( ) differ in the action taken when the requested language environment 
cannot be initialized (see ERRORS below). 

RETURN VALUE 

nl_init ( ) and langinit ( ) return if the environment is successfully initialized to the requested 
language. Otherwise, they return -1. 

ERRORS 

nl_init() fails if the string specified by langname does not identify a valid language name (see 
lang(3C)), or the language is not available on the system. 

If nl_init ( ) fails but had previously succeeded, operation continues with the environment initialized by 
the last successful call. If nl_init ( ) fails and has never been called successfully, the environment 
reverts to the default-mode language n-computer. 

If langinit ( ) fails, the environment reverts to the default-mode language n-computer. 

WARNINGS 

nl_init() and langinit () are provided for historical reasons only. Use setlocale() instead 
(see setlocale(3C)). The default processing language for setlocale() is "C"; the default processing 
language for nl_init() is n-computer. This is maintained for backward portability. 

langinit ( ) is implicitly called by the macros and routines which use a langid parameter (see ctime(3C), 
langinfo(3C), nl_conv(3C), nl_ctype(3C), nl_string(3C), and strtod(3C)). Using any langid parameter rou- 
tine or macro initializes the environment of the associated language name, thus affecting the behavior of 
other routines that interact with the NLS environment. For maximum portability and performance, use of 
macros and routines without the langid parameter is recommended. 

AUTHOR 

nl_init ( ) was developed by HP. 

SEE ALSO 

conv(3C), ctime(3C), ctype(3C), ecvt(3C), langinfo(3C), multibyte(3C), nl_conv(3C), nl_ctype(3C), 
nl_langinfo(3C), nl_string(3C), nl_tools_16(3C), printf(3S), printmsg(3C), scanf(3S), string(3C), strtod(3C), 
vprintf(3S), environ(5), hpnls(5), lang(5), nl_langinfo(5). 

STANDARDS CONFORMANCE 

nl_init():XPG2 

o 
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NAME 

nl_langinfo() - language information 

SYNOPSIS 

#include <langinfo.h> 

char *nl_langinfo(nl_item item); 

DESCRIPTION 

nl_langinf o( ) returns a pointer to a null-terminated string containing information relevant to a par- 
ticular language or cultural area defined in the program's locale (see setlocale(ZC)). The manifest constant 
names and values of item are defined in <langlnf o .h>. For example: 

nl_langinfo( ABDAY_1 ) 

returns a pointer to the string "Dom" if the language identified by the current locale is Portuguese, and 
"Sun" if the identified language is Finnish. 

If an invalid item is specified, a pointer to an empty string is returned. An empty string can also be 
returned for a valid item if that item is not applicable to the language or customs of the current locale. For 
example, a thousands separator is not used when writing numbers according to the customs associated with 
the Arabic language. 

EXTERNAL INFLUENCES 
Locale 

The string returned for a particular item is determined by the locale category specified for that item in lan- 
ginfo(5). 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

WARNINGS I 

nl_langinf o ( ) returns a pointer to a static area that is overwritten on each call. ™ 

AUTHOR 

nl_langinf o ( ) was developed by HP. 

SEE ALSO 

localeconv(3C), setlocale(3C), hpnls(5), langinfo(5). 

STANDARDS CONFORMANCE 

nljanginfo: XPG2, XPG3 
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NAME 

strcmp8(), strncmp8(), strcmpl6(), strncmpl6() - non-ASCII string collation 

SYNOPSIS 

#include <nl_types.h> 

int strcmp8( 

const unsigned char *s1, 

const unsigned char *s2, 

int langid, 

int *status 
); 

int strncmp8 ( 

const unsigned char *sl, 

const unsigned char *s2, 

size_t n, 

int langid, 

int *status 
); 

int strcmpl6 ( 

const unsigned char *sl, 

const unsigned char *s2, 

const unsigned char *f ile_name, 

int *status 
); 

int strncmpl6( 

const unsigned char *sl, 

const unsigned char *s2, 

size_t n, 

const unsigned char *file_name, 

int *status 
); 

DESCRIPTION 

st rcmpS ( ) Compares string si and s2 according to the collating sequence of the NLS environment 

specified by langid (see lang(5)). If langid is invalid, or if the NLS environment 
corresponding to langid is unavailable, n-computer, the default NLS environment 
associated with langinit ( ) is used (see nl_init(3C)). An integer greater than, 
equal to, or less than is returned, depending on whether si is, respectively, greater 
than, equal to, or less than s2. Trailing blanks in strings si and s2 are ignored. 

stmcmpB ( ) Same as strcmp8 ( ) , but looks at a maximum of n characters. 

strcmpl6 ( ) Compares strings si and s2 and returns an integer greater than, equal to, or less than 

depending on whether si is, respectively, greater than, equal to, or less than s2. 
Strings si and s2 can contain 16-bit characters mixed with 7-bit and 8-bit characters 
(see hpnls(5)). Strings si and s2 are compared, with 8-bit characters collating before 
16-bit characters. 

st rncmpl 6 ( ) Same as s t rcmp 1 6 ( ) , but looks at a maximum of n characters. 

nl_init() must be called before the first call to strcmpl6() or strncmpl6() (see nl_init(3C)). 

ERRORS 

If an error condition is encountered, the integer pointed to by status is set to one of the non-zero values 
(listed below) defined in <langinf o.h>. For ENOCPPILE and ENOLPILE, errno indicates that a file 
system call failed. 

[ENOCFFILE] Attempt to access file /usr/lib/nls/conf ig has failed. 

[ENOCONV] The entry for the language sought is not in the file /usr/lib/nls/conf ig. 
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[ENOLFILE] Access to the NLS environment corresponding to langid or file_name has failed. 

WARNINGS 

These routines are provided for historical reasons only. Use strcoll() instead (see st ring (3 C)). How- 
ever, note that all characters are significant to strcoll ( ) , whereas strcmp8 ( ) and strncmp8 ( ) 
ignore trailing blanks. 

strcmpl6() and strncmpl6() do not support a collation sequence table. (A null string must be 
passed as file_name to maintain the correct argument count.) 

strcmp8() and strncmp8() call langinitO (see nl_init(SC)) to load the NLS environment accord- 
ing to the language specified by langid . 

AUTHOR 

nl_str ing ( ) was developed by HP. 

SEE ALSO 

nl_init(3C), string(3C), hpnls(5), lang(5). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of the bytes within the string arguments to 
strcmp8 ( ) , strncmpS ( ) , strcmpl6 ( ) , and strncmpl6 ( ) as single- and/or multi-byte charac- 
ters. 

The LC_COLLATE category determines the collation ordering used by the strcmp8() and 
st rncmp8 ( ) . See hpnls(5) for a description of supported collation features. See nlsinfo(l) to view the col- 
lation used for a particular locale. 

International Code Set Support 

Single- and multi-byte character code sets are supported. ■ 
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NAME 

firstof2(), secof2(), byte_status(), c_colwidth(), FIRSTof2(), SECof2(), BYTE_STATUS( ), C_COLWIDTH(), 
CHARATO, ADVANCEO, CHARADVO, WCHARO, WCHARADVO - tools to process 16-bit characters 

SYNOPSIS 

#include <nl_ctype.h> 

int firstof2(int c); 

int secof2(int c) ; 

int byte_status(int c, int laststatus) ; 

int c_colwidth(int c); 

int PIRSTof2(int c); 

int SECof2(int c); 

int BYTE_STATUS ( int c, int laststatus); 

int C_COLWIDTH(int c); 

int CHARAT (const char *p); 

int ADVANCE (const char *p) ; 

int CHARADV( const char *p) ; 

int WCHAR(wchar_t wc, char *p) ; 

int WCHARADV (wchar_t wc, char *p); 

void PCHAR(int c, char *p) ; 

void PCHARADV(int c, char *p); 

Remarks 

All interfaces listed above whose names begin with a capital letter are implemented as macros; the others 
are functions. 

DESCRIPTION 

The following macros and routines perform their operations based upon the loaded NLS environment (see 
setlocale(3C)). 

PIRSTof 2 ( ) Takes a byte and returns a non-zero value if it can be the first byte of a two-byte char- 

acter according to the NLS environment loaded, and zero if it cannot. 

SECof 2 ( ) Takes a byte and returns a non-zero value if it can be the second byte of a two-byte 

character according to the loaded NLS environment, and zero if it cannot. 

BYTE_STATUS ( ) Returns one of the following values based on the value of the current byte in c and the 
status of the previous byte interpreted in laststatus as returned by the last call to 
BYTE_STATUS ( ) . These are the status values as defined in <nl_ctype . h>: 

ONEBYTE Single-byte character 

SECOP2 Second byte of two-byte character 

PIRSTOP2 First byte of two-byte character 

To validate a two-byte character, both the first and second bytes must be valid. If the value of laststatus 
is PIRSTOP2 but SECof 2 (c) returns false, BYTE_STATUS (c , laststatus) returns ONEBYTE. 

C_COLWIDTH() 
Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, 
and returns the number of columns the character would occupy on a terminal display. 

For the macros FIRSTof 2 ( ) , SECOof 2 ( ) , BYTE_STATUS ( ) , and C_COLWIDTH ( ) results are 
undefined for values of c less than -1 (EOF) or greater than 255. 

CHARAT ( ) 
Takes as an argument a pointer p, which is assumed to be pointing at either a one-byte character or the 
first byte of a two-byte character. In either case, CHARAT ( ) returns the wchar_t value that 
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corresponds to the character pointed to by p . 

ADVANCE ( ) 
Advances its pointer argument by the byte width of the character it is pointing at (either one or two 
bytes). 

CHARADVO 
Combines the functions of CHARAT ( ) and ADVANCE ( ) in a single macro. It takes as an argument a 
pointer p, which is assumed to be pointing at either a one-byte character or the first byte of a two-byte 
character. In either case CHARADV ( ) returns the wchar_t value that corresponds to the character 
pointed to byp, and advances p beyond the last byte of the character. 

WCHARO 
Converts the wchar_t value wc into the corresponding one or two byte character, and writes it at the 
location specified by p . WCHAR ( ) returns the wchar_t value wc . 

WCHARADVO 
Combines the functions of WCHAR ( ) and ADVANCE ( ) in a single macro. It converts the wchar_t 
value wc into the corresponding one or two byte character, and writes it at the location specified by p , 
then advances p past the last byte. WCHARADV ( ) returns the wchar_t value wc . 

firstof2() 

secof2 () 

bfNibroHtiBifcirar&ions of the corresponding macros. These functions can be called from languages other 

cthanlSzidthO 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of single and/or multi-byte characters. 

WARNINGS 

For maximum portability, use the routines documented in the multibyte(3C) manual entry for multi-byte 
character processing. 

Other macros listed in this manual entry cannot be used as the first argument to WCHARO or 
WCHARADVO. For example, 

*t++ = *f++ 
cannot be replaced by 

WCHARADV (CHARADV (f),t). 
Instead, use a method such as 

int c; ... c - CHARADV (f), WCHARADV (c,t). 

WCHARO and WCHARADVO may produce a "null effect" warning from Until) if not used as part of 
another expression or as part of a statement. This does not affect the functionality of either macro. 

Note that WCHAR ( ) and WCHARADV ( ) are not "replace_char" macros. They do not prevent the second 
byte of a two-byte character from being left dangling if WCHAR ( ) or WCHARADV ( ) overwrite the first byte 
of the two-byte character with a single-byte character. 

CHARAT ( ) , ADVANCE ( ) , and CHARADV ( ) do not examine the byte following the location pointed to by 
the argument to verify its validity as a SECof 2 byte. 

AUTHOR 

nl_tools_16 ( ) was developed by HP. 

SEE ALSO 

setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). 
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NAME 

nlappend() - append the appropriate language identification to a valid MPE file name 

SYNOPSIS 

ttinclude <portnls.h> 

void nlappend( 

char *filename, 

short int langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlappend ( ) replaces the first three blanks found in filename with the language number. Its purpose is 
to identify the language of a file in an operating system-independent manner. 

Arguments to nlappend ( ) are used as follows: 

filename A string of up to eight ASCII characters terminated by three blanks. 

langid A short integer specifying the language ID. 

err The first element contains the error number. The second element is always zero. If 

the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

4 Filename is not terminated by 3 blanks. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnlsib) for HP-UX NLS support. 

AUTHOR 

nlappend ( ) was developed by HP. 

SEE ALSO 

portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlcollate() - compare two character strings according to the MPE language-dependent collating sequence 

SYNOPSIS 

ttinclude <portnls.h> 

void nlcollate( 

const char *stringl, 

const char *string2, 

short int length, 

short *rssult 

short int langid, 

unsigned short int err [2], 

const char *collseq 
); 

DESCRIPTION 

nlcollate collates two character strings according to the collating sequence of the specified language. This 
routine's purpose is to determine a lexical ordering. It is not intended to be used for searching or matching. 

If the collseq parameter points to the null address, and langid is specified as (or defaults to) a language in 
which binary collation is appropriate, the binary collation is used to compare the two indicated strings. 
Otherwise, the collseq array is used to determine the string-compare operation (note that this may be a 
binary collation). 

Arguments to nlcollate () are as follows: 

string 1 One of the character strings to be collated. 

string2 The second character string to be collated. 

length The length of the string segments to be collated. 

result The result of the character collation is stored in the short integer variable to which 

result points. 

If string 1 collates equal to string2 . 
- 1 If string 1 collates before string2. 

1 If stringl collates after string2 . 

langid 
The language ID indicating the collating sequence to be used for the collation. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid collating table entry. 

4 Invalid length parameter. 

collseq 
An array containing the collating sequence to be used, as returned from a call to nlinfo(SX)'s item- 
number 11. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlcollate was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 
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EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlconvclockO - check and convert time string to MPE internal format 

SYNOPSIS 

#include <portnls.h> 

unsigned int nlconvclock ( 

const char * instr, 

short int leninstr, 

short Int langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlconvclock ( ) converts instr to a general time format as returned by nlinfo(3X) itemnumber 3. This 
routine is the inverse of nlfmtclock(3X). Note that the seconds and tenths of seconds are always set to zero. 

The arguments to nlconvclock ( ) are used as follows: 

instr A character buffer containing the time to be converted. 

leninstr An unsigned short specifying the length of the buffer. 

langid A short containing the language ID. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid time format. 

4 Invalid length. 

RETURN VALUE 

nlconvclock ( ) returns the time in the format: 



Bits 



15 



Hour of Day 


Minute of Hour 



Bits 16 



23 24 



31 



Seconds 


Tenths of Seconds 



WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlconvclock ( ) was developed by HP. 

SEE ALSO 

clock(3X), nlfmtclock(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlconvcustdate() - convert date string to MPE packed date format 

SYNOPSIS 

#include <portnls.h> 

unsigned short nlconvcustdate ( 

const char * instr, 

short int leninstr, 

short int langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlconvcustda() converts instr to a packed date format. This routine is the inverse of 
nlfmtcustdate(3X). 

Arguments to nlconvcustda ( ) are as follows: 

instr A character buffer containing the date to be converted. 

leninstr A positive integer specifying the length of the string (in bytes). 

langid A short containing the language ID number. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid date format. 

4 Invalid string length. 

RETURN VALUE 

The routine returns the date as an unsigned integer in the format: 

Bits 6 7 15 



Year of Century 


Day of Year 



WARNINGS 

This routine is provided for compatibility with MPE, another HP operating system. See portnls(5) for more 
information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlconvcustda ( ) was developed by HP. 

SEE ALSO 

calendar(3X), nlfmtcustdate(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlconvnum() - convert MPE native-language formatted number to ASCII number 

SYNOPSIS 

#include <portnls.h> 

void nlconvnum( 

short int langid, 

const char * instr, 

short int leninstr, 

char * outstr 

short int *plenoutstr, 

unsigned short int err [2], 

const char *numspec / 

short int fmtmask, 

short int *pdecimals 
); 

DESCRIPTION 

nlconvnum( ) converts a native-language formatted number to an ASCII number, with an n-computer 
decimal separator ( . ) and thousands separator (, ), to use for further conversion to INTEGER, REAL, etc. 

This routine converts the decimal separator and the thousands separators to the n-computer equivalent, or 
strips them, according to the value of fmtmask. If fmtmask and M_NUMBERSONLY is not zero, instr is 
validated as a number. If it is null, no validation takes place. 

For languages using an alternate set of digits (currently only arabic, which uses HINDI digits), 
nlconvnum( ) also converts these digits to ASCII digits so they can be recognized and used as numeric 
characters. 

Arguments to nlconvnum( ) are as follows: 

langid A language ID number. 

instr A character buffer containing the native language formatted number to convert. 

Leading and trailing spaces are ignored. 

leninstr Length, in bytes, of instr. 

outstr Output buffer; an array containing the converted output. The output is left-justified 

in the buffer, and plenoutstr contains the actual length of the converted number, out- 
string may refer to the same address as instr. 

plenoutstr A pointer to the length, in bytes, of outstr. After a successful call to nlconvnum, the 

short integer to which plenoutstr points contains the actual length of the converted 
number. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid length specified (leninstr or plenoutstr). 

4 Invalid number specified (instr). 

7 Truncation has occurred (outstr is left partially formatted). 

8 Invalid numspec parameter. 

9 Invalid fmtmask parameter. 

numspec 
A character buffer, as returned from nlnumspec, containing information about correct formatting. If 
this parameter is not null, langid is ignored and performance is improved (see the description of 
nlnumspec). 

fmtmask 
An unsigned short specifying how to format the number. The default value is zero, which means substi- 
tution only, convert thousands separators, convert decimal separators, and that instr can contain any 
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Value Description 

M_STRIPTHOU Strip thousands separators. 

M_STRIPDEC Strip decimal separators. 

M_NUMBERSONLY instr contains a number. 

pdecimals 
Pointer to a variable in which the number of decimal places in the input number is returned. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlconvnum( ) was developed by HP. 

SEE ALSO 

nlfmtnum(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfindstrO - search for a string in another string using the MPE character set definition 

SYNOPSIS 

#include <portnls.h> 

short int nlfindstr ( 

short int langid, 

const char * stringl, 

short int lengthl, 

const char *string2.. 

short int length2, 

unsigned short int err [2], 

const char *charset 
); 

DESCRIPTION 

nlfindstr ( ) searches for the first occurrence of a given string of characters in another character string. 

Arguments to nlfindstrO are: 

langid The ID number of the desired language. 

stringl A pointer to the character buffer to be searched. It can contain single-byte and two- 

byte characters. 

lengthl Length (in bytes) of stringl . 

string2 The character buffer for which to search. 

Iength2 Length (in bytes) o£string2 . Iength2 must be less than or equal to lengthl . 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid lengthl parameter. 

4 Invalid length2 parameter. 

charset 
A byte buffer containing the character set definition for the language to be used, as returned by 
nlinfo(SX)'s itemnumber 12. 

RETURN VALUE 

offset is a short integer that holds the number of bytes into stringl where string2 was found, 
nlf indst r ( ) returns -1 if the string is not found. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfindstr ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), mpnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtcalendarO - format an MPE packed date using a localized format 

SYNOPSIS 

#include <portnls.h> 

void nlfmt calendar ( 

unsigned short int date, 

char *outstr, 

short int langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlfmtcal ( ) formats the specified date in the localized custom version of the date format, but with no 
time information (see nlfmtclock(8X)). For example: 

FRI, OCT 2, 1987 

Arguments to nlfmtcal ( ) are used as follows: 

date An unsigned short indicating the date in the packed date format: 

Bits 6 7 15 



Year of Century 


Day of Year 



outstr 
A character buffer in which the formatted date is returned. This buffer is 18 bytes long, and padded 
with blanks if necessary. 

langid 
A short integer specifying the language whose custom is to be used. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid date format. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfmtcal ( ) was developed by HP. 

SEE ALSO 

calendar(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtclock() - format MPE time of day using localized format 

SYNOPSIS 

ttinclude <portnls.h> 

void nlf mt clock ( 

unsigned int time, 
char *outstr, 
short int langid, 
unaianed short int errT21 

); 

DESCRIPTION 

nlfmtclock( ) formats the time of day obtained with the clock routine, according to the clock format 
defined for the specified language. 

Arguments to nlfmt clock ( ) are used as follows: 

time An unsigned int obtained from the clock routine: 

Bits 7 8 15 



Hour of Day 


Minute of Hour 



Bits 16 23 24 31 



Seconds 


Tenths of Seconds 



outstr 
An 8-byte buffer in which the formatted time of day is returned. 

langid 
A short integer specifying the language whose clock format is to be used. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid time format. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfmt clock ( ) was developed by HP. 

SEE ALSO 

clock(3X), nlconvclock(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtcustdate() - format an MPE packed date using a custom date 

SYNOPSIS 

#include <portnls.h> 

void nlf mtcustdate ( 

char *outstr, 
short int langid, 
unsigned short int err [2] 
); 

DESCRIPTION 

nlfmtcustdate ( ) converts the packed date format to the language-dependent custom date as specified 
in the language definition file. A custom date has an abbreviated format such as 10/21/87 or 
87.10.21. 

Arguments to nlfmtcustdate ( ) are used as follows: 

date An unsigned short containing the date in the packed date format: 

Bits 6 7 15 



Year of Century 


Day of Year 



outstr 
A 13-byte buffer in which the formatted date is returned. 

langid 
A short integer of the language whose custom date specification is to be used for the format. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid date format. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfmtcustdate ( ) was developed by HP. 

SEE ALSO 

calendar(3X), nlconvcustdate(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtdateO - format MPE date and time in a localized format 

SYNOPSIS 

ttinclude <portnls.h> 

void nlf mtdate ( 

unsigned short int date, 

unsigned long int time, 

char *outstr, 

short int lan^id- 

unsigned short int err [2] 
); 

DESCRIPTION 

nlf mtdate ( ) formats the specified date and time in a localized custom version. For example: 

SUN, FEB 7, 19 88 9:00 AM 
Arguments to nlf mtdate ( ) are used as follows: 

date An unsigned short indicating the date to be formatted in the packed date format: 

Bits 6 7 15 



Year of Century 


Day of Year 



time 
An unsigned int indicating the time to be formatted. The double word is in the clock format: 

Bits 7 8 15 



Hour of Day 


Minute of Hour 



Bits 16 23 24 31 



Seconds 


Tenths of Seconds 



outstr 
A 28-byte buffer in which the formatted date is returned. 

langid 
A short containing the language ID indicating the custom to be used. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid date format. 

4 Invalid time format. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls{h) for HP-UX NLS support. 

AUTHOR 

nlf mtdate ( ) was developed by HP. 

SEE ALSO 

calendar(3X), clock(3X), nlfmtcal(3X), nlfmtclock(3X), portnls(5). 



HP-UX Release 9.0: August 1992 



-1 



645 



nlf mtdate (3X) nlfmtdate ( 3X) 



EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtlongcalO - format an MPE packed date using a long calendar format 

SYNOPSIS 

#include <portnls.h> 

void nlfmtlongcal ( 

unsigned short int date, 

char *outstr, 

short int langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlfmtlongcal () formats the supplied date according to the long calendar format. The formatting is 
done according to the template returned by nlinfo(3X), itemnumber 30. 

Arguments to nlfmtlongcal ( ) are used as follows: 

date A short integer value containing a date in the packed date format: 

Bits 6 7 15 



Year of Century 


Day of Year 



outstr 
A 36-byte buffer to which the formatted long calendar date is returned, padded with blanks if necessary. 

langid 
An ID number specifying which language-specific format is to be used. 

err 
The first element of this array contains the error number. The second element is always zero. If the call 
is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid date format. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfmtlongcal ( ) was developed by HP. 

SEE ALSO 

calendar(3X), nlfmtcalendar(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlfmtnumO - convert an ASCII number to an MPE language-specific formatted number 

SYNOPSIS 

ttinclude <portnls.h> 

void nlfmtnum( 

const char *instr / 
short int leninstr, 
char *outstr, 
short int *plenoutstr, 
unsigned short int err [2], 
const char *itujrspsc 
short int fmtmask, 
short int decimals 
); 

DESCRIPTION 

nlfmtnum ( ) converts a string containing an ASCII number to a language-specific formatted number using 
the currency name/symbol, decimal separator, and thousands separators defined for the language. The 
string may contain the n-computer decimal separator ( . ), thousands separator (, ), and a dollar sign ($). 

This routine operates in two modes: substitution mode and formatting mode. The substitution mode (if 
fmtmask is zero) substitutes the native equivalent for . and , and, for arable, the alternate set of digits 
for ASCII digits. The input is not validated as a number, and can contain several individual numbers. No 
justification takes place, and the output is left-truncated if outstr is shorter than instr (for example, 
1,234. 56 becomes 234,56). 

If fmtmask is not zero, the formatting mode formats the input according to fmtmask in addition to perform- 
ing the substitution. In this mode the input is validated as a number and only ASCII digits and -, +, $, . , 
and , are allowed. Only one sign and one $ is allowed and they must be the first character(s) in instr. 
Even if insertion (of thousands separators, etc.) is specified in fmtmask, thousands separators and a 
decimal separator are still valid characters in the input. In this case they are substituted. If no 
justification is specified, the output is right-justified with the same number of trailing spaces as the input. 
Note that for languages written right-to-left, trailing spaces in the input are preserved as leading spaces in 
the output. If the output is truncated, it is left-truncated (for example, 1, 234 . 56 becomes .234,56). 

Arguments to nlfmtnumO are used as follows: 

langid A language ID number specifying which language's formatting specifications to use for 

the formatting. 

instr A byte array containing the n-computer formatted ASCII number to be converted, for 

example, 123,456.78. Leading and trailing spaces are allowed. 

leninstr Length, in bytes, of instr. 

outstr A byte buffer where the language-specific formatted number is returned. The decimal 

separator, thousands separator, and currency symbol/name are replaced according to 
the language definition, if present or inserted, or if specified by fmtmask. outstr can 
reference the same address as instr. 

plenoutstr Length, in bytes, of outstr. After a successful call, if specified by fmtmask (the two 

bits starting with bit 12 (from highest to lowest) are equal to 3), plenoutstr returns 
the actual length, in bytes, of the formatted number. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured, 

3 Invalid length specified (leninstr or *plenoutstr). 

4 Invalid number specified (instr). 
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5 Invalid decimal point in number specified (instr). 

6 Invalid thousand separators in number specified (instr). 

7 Truncation has occurred (outstr is left partially formatted). 

8 Invalid numspec parameter. 

9 Invalid fmtmask parameter. 

1 Invalid decimals parameter. 

numspec 
A byte array, as returned from nlnumspec ( ) , containing formatting specifications for the specified 
language (currency symbol/name, decimal separator, etc.). If this parameter is not null, langid is 
ignored, and performance is improved. (See nlnumspec(oX)). 

fmtmask 
A short integer value specifying any formatting to be done on the input. The default value is zero, 
which means a simple substitution. 

Value Description 

NULL Do not insert thousands separators. 

Do not insert decimal separator. 
No justification of the output. 

M_INSTHOU Insert thousands separators. 

M_INSDEC Insert decimal separator. 

M_CURRENCY Insert currency name/symbol. 

M_LEFT JUST The output is left-justified. 

M_RIGHTJUST Right-justify the output. 

M_RETLENGTH Left-justify the output and return the actual length of the formatted number 
in plenoutstr 

decimals 
An integer specifying where to insert the decimal separator. The value is ignored it fmtmask and 
M_INSDEC are zero, or a decimal separator is present in the number. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlfmtnum ( ) was developed by HP. 

SEE ALSO 

nlconvnum(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlgetlangO - return the current user, data, or system default language 

SYNOPSIS 

#Include <portnls.h> 

short int nlgetlang( short lnt function, unsigned short int err[2]); 

DESCRIPTION 

nlget lang ( ) looks for a LANG string in the user's environment. If it finds it, it returns the correspond- 
ing integer as described in lang(5). Otherwise, or if the value of function is not valid, it returns and sets 
the err parameter. 

Arguments to nlgetlangO are used as follows: 

function A short integer that specifies which language is returned. 

Value Description 

1 User language 

2 Data language 

3 System default language 
err 

The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 
Error # Meaning 

1 Native Language Support file(s) not found 

2 Specified language not configured 

3 Invalid function value 

4 No language specified for nlget lang ( ) to access 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

nlget lang ( ) returns the language ID as a short integer. In case of error, zero is returned. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this function. Use the Native Language Support routines for C program- 
mers described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlget lang ( ) was developed by HP. 

SEE ALSO 

getenv(3C), currlangid(3C), portnls(5). 
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NAME 

nlinfoO - return MPE language-dependent information 

SYNOPSIS 

#include <portnls.h> 

void nlinfo( 

short int itemnumber, 

int *itemvalue, 

short int *langid, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlinf o ( ) returns such information as the format of the date, the radix character, the direction of the 
language, etc. 

The itemnumber indicates the type of information the user has requested. The data is passed back in item- 
value. 

The arguments to nlinf o ( ) are used as follows: 

itemnumber A short integer of the item desired. This number specifies which item value is to be 
returned. See below for a list of item numbers. 

itemvalue A pointer to an integer that contains the value of the item specified by the correspond- 

ing item number. The data type of the item value depends on the item itself. 

langid A pointer to a short integer containing the language ID or, for itemnumber 22, the 

location in which the language ID is returned. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

1 Native Language Support file(s) not found 

2 Specified language is not configured. 

3 Specified character set is not configured. 
1 itemnumber is out of range. 

Item numbers 

The following is a list of the currently defined item numbers and the information returned. 

itemnumber Description 

1 An 18-byte buffer in which the calendar format is returned. 

2 A 13-byte buffer in which the custom date format is returned. 

3 An 8-byte buffer in which the clock specification is returned. 

4 A 48-byte buffer in which the month denotation abbreviation table is returned. The abbre- 
viation of each month is 4 bytes long (with blank padding if necessary). The first 4 bytes 
are the abbreviation for January. 

5 A 144-byte array in which the month denotation table is returned. Each month denotation 
is 12 bytes long. The table starts with January. 

6 A 21-byte array in which the day of the week denotation abbreviation table is returned. 
Each weekday abbreviation is three bytes long. The first three bytes are the abbreviation 
for Sunday. 

7 An 84-byte array in which the day of the week denotation table is returned. Each weekday 
denotation is 12 bytes long. The table starts with Sunday. 

8 A 12-byte array in which the YES/NO responses are returned. The first 6 bytes contain the 
(upshifted) "YES" response; the second 6 bytes contain the (upshifted) "NO" response. 
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9 A 2-byte array in which the symbols for decimal point and thousands indicator are 
returned. The first byte contains the decimal point, the second contains the thousands 
indicator. 

10 A 6-byte array in which the currency signs are returned. The first byte contains the 
currency sign used in the business formats, the second byte is either a numeric zero, which 
indicates that the currency symbol precedes the value, or a one, which indicates that a sym- 
bol follows the value. The next 4 bytes contain the fully qualified currency sign. 

11 An array in which the collating sequence table is returned. To determine the size of this 
array, the length must be determined by a call to nllnf o ( ) with itemnumber 27 '. 

12 A 256-byte array in which the character set definition is returned. Each byte has numeric 
identification of the character type: 

Numeric character 

1 Alphabetic lowercase character 

2 Alphabetic uppercase character 

3 Undefined graphic character 

4 Special character 

5 Control code 

6 First byte of a two-byte character 

15 
A 256-byte array in which the upshift table is returned. 

16 
A 256-byte array in which the downshift table is returned. 

17 
An array of unsigned shorts in which the language numbers of all configured languages are returned. 
The first element of this array contains the number of configured languages. The second word contains 
the language number of the first configured language, etc. The system default language is returned (the 
langid parameter, if specified, is insignificant). 

18 
A short int in which true (-1) is returned if the specified language is supported (configured) on the sys- 
tem. Otherwise, false (0) is returned. 

21 
A 16-byte array in which the (uppercase) name of the specified language is returned. If the name con- 
tains less than 16 bytes, it is padded with blanks. 

22 
The itemvalue contains a byte buffer containing a language name or language number (ASCII digits) ter- 
minated by a blank. The array must contain less than or equal to 16 bytes. The langid (third) parame- 
ter is assigned the associated language ID number. 

26 
A short integer in which the class number of the specified language is returned. 

27 

An integer in which the length (in two-byte units) of the collating sequence table corresponding to the 
specified language is returned. 

28 

A short integer in which the length (in two-byte units) of the national dependent information table is 
returned. If no national table exists for the specified language, an error is returned. 

29 
A byte buffer in which the national-dependent information table is returned. To determine the size of 
this array, the length must be obtained via a prior call to nlinf o ( ) with itemnumber 28. 

30 
A 36-byte array in which the long calendar format is returned. It may contain arbitrary text as well as 
the following descriptors: 
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D 1 through 3 of these are to be replaced by that many bytes from the day abbreviation. 

W 1 through 12 of these are to be replaced by that many bytes from the day of the week. 

M 1 through 4 of these are to be replaced by that many bytes from the month abbrevia- 
tion. 

1 through 12 of these are to be replaced by that many bytes from the month of the year, 

mm Numeric month of the year. 

yy Numeric year of the century. 

yyyy Numeric year of the century. 

Nyy National year. 

In addition, a special literal character - (tilde) can be used to indicate that the following character 
should be taken literally in the format, even if it is one of the special characters above. 

For example, a format could be: 

"WWWWWWWWW, OOOOOOOOO dd, a.~d. yyyy " 

This format in n-computer would result in the following: 
"WEDNESDAY, NOVEMBER 21, A.D. 1984 " 

31 
A 16-byte array in which the currency name is returned. 

32 

An 8-byte array, containing information about an Alternate set of digits (currently only used by ara- 
ble). 

Byte Description 

0-1 Alternate digit indicator 

- No Alternate digits defined ■ 

1 - Alternate digits denned | 

2 The Alternate digit 

3 The Alternate digit 9 

4 The + used with Alternate digits 

5 The - used with Alternate digits 

6 The decimal separator used with Alternate digits 

7 The thousands separator used with Alternate digits 

33 

A 4-byte array, containing information about the direction of the language. 

Byte Description 

1 Language direction 

- Direction is "left-to-right" 

1 - Direction is "right-to-left" 

2 The "right-to-left" space 

3 Undefined 

34 
An unsigned short that returns the data ordering of the language. 

Keyboard order 

1 Left-to-Right screen order 

2 Right-to-Left screen order 

35 
An unsigned short that returns the size of the character used by the language. 

One-byte characters (8 bits) 

1 Two-byte characters (16 bits) 
WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 
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AUTHOR 

nl info ( ) was developed by HP. 
SEE ALSO 

hpnls(5). 
EXTERNAL INFLUENCES 

International Code Set Support 

Sinsle- and multi-byte character code sets 



I 



654 - 4 - HP-UX Release 9.0: August 1992 



nlist(3C) nlist(3C) 



NAME 

nlist() - get entries from name list 

SYNOPSIS 

#include <nlist.h> 

int nlist (const char *f ile_name / struct nlist *nl); 

Remarks 

The use of symbol table type and value information is inherently non-portable. Use of nlist ( ) should 
reduce the effort required to port a program that uses such information, but complete portability across all 
HP-UX implementations cannot be expected. 

DESCRIPTION 

nlist ( ) examines the name list in the executable file whose name is pointed to by file_name, and selec- 
tively extracts a list of values and puts them in the array of nlist ( ) structures pointed to by nl. The 
array of nlist () structures initially contains only the names of variables. Once nlist () has been 
called, the variable names are augmented with types and values. The list is terminated by a null name, 
which consists of a null string in the variable-name position of the structure. The name list of the file is 
searched for each variable name. If the name is found, type and value information from the file is inserted 
into the name list structure. If the name is not found, type and value fields are set to zero. The structure 
nlist is defined in the include file <nlist .h>. See a.out(4) and nlist(4) for further description of the 
symbol table structure. 

The file must have the organization and symbol table described for an a . out file in a.out(4). The informa- 
tion is extracted from the symbol table used by the loader, IdiX). 

On machines that have such a file, this subroutine is useful for examining the system name list kept in file 
/hp-ux. In this way programs can obtain system addresses that are up to date. 

RETURN VALUE 

All nlist structure fields are set to if the file cannot be found or if it is not a valid object file containing a 
linker symbol table. 

nl is t ( ) returns -1 upon error; otherwise it returns 0. 

WARNINGS 

The <nlist . h> header file is automatically included by <a . out . h> for compatibility. However, includ- 
ing <a . out .h> is discouraged if the only information needed from <a . out .h> is for use by nlist () . If 
<a . out . h> is included, the line #undef n_name may need to follow it. 

SEE ALSO 

a.out(4), nlist(4). 

STANDARDS CONFORMANCE 

nlist: SVID2 



I 
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NAME 

nljudge() - judge whether a character is a one-byte or multi-byte Asian character using MPE character 
definition table 

SYNOPSIS 

#include <portnls.h> 

short int nljudge( 

short int langid, 

const char * instr, 

short int length, 

char *judgeflag, 

unsigned short int err [2], 

const char *charset 
); 

DESCRIPTION 

nl judge ( ) judges whether or not a character is a one-byte or multi-byte Asian character. If it is a multi- 
byte character, judgeflag is set to 1 or 2. If it is a one-byte character, judgeflag is set to 0. 

Any language number can be specified as the langid parameter. However, if the language specified uses 
only one-byte characters (see nlinfo(3X)'s itemnumber 35), the judgeflag returns all zeroes. 

Arguments to nljudge() are used as follows: 

langid The ID number for the desired language. 

instr The character buffer to be judged. 

length A short integer value specifying the number of bytes in instr. 

judgeflag A pointer to a char whose value is set to: 

One-byte character 

1 First byte of a two-byte character 

2 Second byte of a two-byte character 

3 Invalid two-byte character 

err 
The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid string length. 

7 Invalid characters found in instr. 

charset 
A character buffer containing the character set definition for the language to be used, as returned by 
nlinfo(3X)'s itemnumber 12. If it doesn't point to a null address, the langid parameter is ignored, and 
this routine is more efficient. 

RETURN VALUE 

nl judge ( ) returns the number of multi-byte Asian characters that could be used to check if a string of 
character contains any Asian characters. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nl judge ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 
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EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlkeycompareO - determine if a character array (keyl) is almost equal to another (key2) using the MPE 
language-dependent collation table 

SYNOPSIS 

#include <portnls.h> 

void nlkeycompare ( 

const char *keyl / 

short int lengthl, 

const char *key2, 

short int length2, 

short int *presult, 

short int langid, 

unsigned short err [2], 

const unsigned short *collseq 
); 

DESCRIPTION 

nlkeycompare ( ) determines if a character array (keyl) is almost equal to another character array 
(key2). Two character arrays are considered almost equal when they differ only in case or accent priorities. 
For example, the arrays ABC and aBc are almost equal in English. 

nlkeycompare ( ) determines if a given character array can be collated before or after another character 
array of a different length. For example, nlkeycompare ( ) examines the records in a file sorted in a 
given language and determines if the character array keyl can be found later on in the file as the leading 
substring of the sort key, if the value of the last record read is key2 . 

Arguments to nlkeycompareO are used as follows: 

keyl A byte array being compared to key2 . 

lengthl The length in bytes of keyl . lengthl must be less than length2 . 

key2 A byte array containing a character array to which to compare keyl . 

Iength2 The length in bytes of key2 . Iength2 must be greater than lengthl . 

presult A pointer to a short integer variable in which to return the result of the comparison. 

The retrieved key2 matches the keyl. 

1 The retrieved key2 does not match the keyl. It is different only in 
case or accent priority. 

2 The retrieved key2 is less than the keyl (its collating order is before 
the desired one). 

3 The retrieved key2 is greater than the keyl (it collates after the 
desired key). 

langid 

The language ID number indicating the collating sequence to be used for the compare. 

err 

The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid collating table entry. 

4 Invalid length parameter. 

7 lengthl is greater than length2. 

collseq 
An array containing the collating sequence table as returned by nlinfoQSXYs itemnumber 11. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
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described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlkeycompare ( ) was developed by HP. 

SEE ALSO 

nlcollate(3X), nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlnumspec() - return information needed by MPE routines for formatting and converting numbers 

SYNOPSIS 

#include <portnls.h> 

void nlnumspec (short int langid, char *nuiaspec, unsigned short err[2]); 

DESCRIPTION 

nlnumspec ( ) returns the information needed for formatting and converting numbers. It combines 
several calls to nlinfo() in order to simplify the use of native language formatting. By calling 
nlnumspec ( ) once, and passing the obtained information to nlfmtnum() and nlconvnum( ), impli- 
cit calls to nlnumspec () from nlfmtnumO and nlconvnum() are avoided and performance is 
improved. 

nlnumspec ( ) combines the functions of rdinfo(SXys itemnumbers 9, 10, 31, 32, and 33. The information 
is formatted where needed. For example, any spaces in the currency symbol/name are included. The 
currency symbol/name is the shortest non-blank descriptor, as returned from nlinfo(3X) itemnumbers 10 
and 31. 

nlnumspec ( ) does not, apart from the mentioned formatting, provide any information not obtainable 
with nlinf o ( ) , but is included for the convenience of the user. For efficiency, the user of this routine 
calls it once, saves the result, and then calls nlf mtnum ( ) and/or nlconvnum ( ) multiple times. 

Arguments to nlnumspec ( ) are used as follows: 

langid The ID number of the desired language. 

numspec A character buffer of at least 60 bytes in which the following information is returned: 

Byte Description 

00-01 Language ID number. 
02-03 Alternate Digit Indicator: 

- No Alternate digits exist. 

1 - Alternate digits exist. 
04-05 Language Direction Indicator. 

- The Language is "left-to-right". 

1 - The Language is "right-to-left". 
06-07 The Alternate digit range ("0", "9"). 

8 Decimal separator (ASCII-digits). 

9 Decimal separator (Alternate-digits). 

1 Thousands separator (ASCII-digits). 

11 Thousands separator (Alternate-digits). 

1 2 V Alternate-digits. 

1 3 "-" Alternate-digits. 

14 "Right-to-left" space. 

1 5 Reserved. 
16-17 Currency place . 

- Currency symbol precedes the number. 

1 - Currency symbol follows the number. 

2 - Currency symbol replaces the decimal separator. 
18-19 Length of Currency symbol (including any spaces). 

2 0-37 Currency symbol (including any spaces). 

38-39 Data ordering of the language. 

40-41 Size of character used by the language. 

42-59 Reserved. 

err 
The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 
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WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls{h) for HP-UX NLS support. 

AUTHOR 

nlnumspec ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlrepcharO - replace non-displayable characters of a string using the MPE character set table 

SYNOPSIS 

#include <portnls.h> 

void nlrepchar( 

const char * instr. 

char *outstr, 

short Int length, 

char repchar, 

short int langid, 

unsigned short int err [2], 

const char *charset 
); 

DESCRIPTION 

nl repchar ( ) replaces all non-displayable characters in the input character buffer with the replacement 
character. Non-displayable characters are those of types 3 and 5, as returned by nlinfo(3X), itemnumber 
12. Native language characters of the supported character set are not replaced. 

Arguments to nlrepcharO are used as follows: 

instr A character buffer in which the non-displayable characters must be replaced. 

outstr A character buffer to which the replaced character string is returned. 

length A short integer specifying the length (in bytes) of instr . 

repchar A byte specifying the replacement character to be used. 

langid A short integer value specifying the language ID number of the language that deter- 

mines the character set to be used. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid replacement character. 

4 Invalid length parameter. 

8 The value of outstr would overwrite instr. 

1 Invalid Asian character. 

charset 
Contains the character set definition for the language to be used, as returned in nlinfo(3X)'s item- 
number 12. If this parameter is supplied (i.e., not NULL), langid is ignored and this routine is much 
more efficient. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nl repchar ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlscanmove() - move, scan and case-shift character strings using the MPE character set definition table 

SYNOPSIS 

ttinclude <portnls.h> 

short int nlscanmove( 

const char * instr, 

char *outstr, 

short int flags, 

int length, 

short int langid, 

unsigned short int err [2], 

const char *pcharset, 

const char *pshift 
); 

DESCRIPTION 

nlscanmove ( ) moves, scans and case-shifts character strings. 

Arguments to nlscanmove () are used as follows: 

instr A character buffer that acts as the source string of the scan or move functions. 

outstr A character buffer that acts as the target. Note that if outstr is equal to instr, this 

routine will act as scan. Otherwise, a move will be performed; see err below. 

flags A flag defining the options for the routine invocation. This parameter defines the end 

condition for the scan or move. 

Value Description 

M_L Select lowercase alphabetic characters. 

M_U Select uppercase alphabetic characters. 

M_N Select numeric characters. 

M_S Select special characters. 

M_WU By default nlscanmove () scans or moves characters while 

the character currently being scanned is one of those selected 
(i.e. upper, lower, numeric, special). If M_WU is used, 
nlscanmove ( ) scans or moves characters until the character 
currently being scanned is one of those selected. 

M_US Shift scanned or moved characters to the uppercase. 

M_DS Shift scanned or moved characters to the lowercase. 

M_OB Select one-byte characters. 

M_TB Select two-byte (Asian) characters. 

M_OB or M_TB 

Select both one- and two-byte characters. 

length 

A short integer indicating the maximum number of valid bytes to be acted upon during the indicated 
option. 



A short integer containing the language ID number which implies the both the character set definitions 
of character attributes and the language specific shift. 

err 

The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 
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Error # Meaning 

2 Specified language is not configured. 

3 Overlapping strings, instr overwrites outstr. 

4 Invalid length parameter. 

7 The reserved part of flags is not zero. 

8 Both upshift and downshift request. 

9 Invalid table element. 

1 Invalid Asian character. 

pcharset 

A pointer to a character buffer containing the character set definition for the language to be used, as 
returned nlinfo(3Xy& itemnumber 12. If not zero, the langid parameter is ignored, and this routine is 
much more efficient. This parameter is required for calls in which bits (12:4) of flags is neither nor 
15. 

pshift 

A pointer to a character buffer containing shift information for a desired upshift or downshift (e.g., as 
returned in nlinfo(SX)'s itemnumber 15 or 16). This parameter is used when bits (9:2) of flags is not 0. 

RETURN VALUE 

A short containing the number of bytes acted upon in the scan or move operation. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nlscanmove ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlsubstr() - extract substring of a string using the MPE character set definition table 

SYNOPSIS 

#include <portnls.h> 

void nlsubstr( 

const char *instring, 

short int inlength, 

char *out string, 

short *pout length, 

short int start, 

short int move length, 

short int langid, 

short int flags, 

unsigned short int err [2], 

const unsigned short int *charset 
); 

DESCRIPTION 

nlsubstr ( ) extracts a substring from instring and places the result in outstring. 

Arguments to nlsubstr () are used as follows: 

instring The byte buffer from which the substring is extracted. The string can contain both 

one-byte and two-byte (Asian) characters. 

inlength Length, in bytes, of instring 

outstring Where the sub-string is placed. 

poutlength Length, in bytes, of outstring. After a successful call, the variable to which poutlength 

points contains the actual length of the sub-string moved to outstring. 

start The offset into instring where the sub-string starts. A value of zero is the beginning 

point. 

movelength Length, in bytes, of the sub-string. 

langid The ID number of the desired language. 

flags This flag word is used primarily with Asian languages. It is meaningless with one- 

byte oriented languages, flags is used to indicate the treatment of the case when the 
first byte of the sub-string is the second byte of a two-byte Asian character and in the 
case where the last byte in the sub-string is the first byte of a two-byte Asian charac- 
ter. 

Selection of nlsubstr ( )'s behavior if the first character is the second byte of an 
Asian character: 

Value Description 

FJRETURNERR Return an error condition. 

P_SPP1 Start from start+1. 

F_SPM1 Start from start-1. 

P_SPBL Start from start, but replace the character with a blank in out- 

string. 

P_SP Start from start, regardless of the value of the first character. 

Selection of nlsubstr ( ) 's behavior if the last character is the first byte of an Asian character: 

Value Description 

P_LMP1 Move until movelength+1 is reached. 

P_LMM1 Move until movelength-1 is reached. 
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P_LMBL Move until movelength is reached, but replace the character with a blank in out- 

^ string. 

I P_LM Move until movelength is reached, regardless of the value of the last byte. 

err 

The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

7 Invalid inlength. 

8 Invalid start. 

9 Invalid movelength. 

1 1 Invalid value in flags bits (8:4). 

1 2 Invalid value for flags bits (12:4). 

13 The start position is the second byte of an Asian character, or an underflow condition 
occurred because of flags. 

14 The end position is the first byte of an Asian character, or an overflow condition 
occurred because of flags. 

charset 

An array containing the character set definition for the language to be used, as returned by 
nlinfo (SX)'s itemnumber 12. 
WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 
AUTHOR 

nlsubstr ( ) was developed by HP. 
SEE ALSO 

nlinfo(3X), portnls(5). 
EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 
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NAME 

nlswitchbufO - convert a string of characters between phonetic order and screen order using the MPE char- 
acter set definition table 

SYNOPSIS 

ttinclude <portnls.h> 

void nlswitchbuf ( 

short int langid, 

const char *instr, 

char *outstr, 

short int length, 

unsigned short int lefttoright, 

unsigned short int err [2] 
); 

DESCRIPTION 

nlswitchbufO is useful for handling data from languages written from right-to-left (e.g., Middle 
Eastern languages). It is used by a program to convert a buffer that is in phonetic order (i.e., the order in 
which the characters would be typed at a terminal or spoken by a person) to screen order (i.e., the order in 
which the characters are displayed on a terminal screen or piece of paper), or vice-versa. Screen order is 
defined as right-to-left if the primary mode of the terminal or printer is from right-to-left (as when it is used 
principally for entering or displaying data from a right-to-left language). Otherwise, screen order is defined 
as left-to-right. 

Phonetic order and screen order are, in general, not the same if USASCII text is mixed with that from a 
right-to-left language. The relationship between phonetic order and screen order is further complicated by 
the Hindi digits in Arabic, which play a third role intermediate between ASCII characters and characters of 
the right-to-left language. 

Note that this is a somewhat special-purpose native language support routine, nlswitchbuf ( ) is use- 
ful only for languages that are written from right-to-left, and which may occasionally mix left-to-right text 
(e.g., English) with right-to-left. Nonetheless, it can be used by a general-purpose (not specifically for han- 
dling right-to-left data) program. Such a program calls nlswitchbuf ( ) to convert data from phonetic 
order to screen order and back again (for example, an editor that wants to track cursor movement on a ter- 
minal against a buffer of text in memory needs to do this). If the data is not that of a right-to-left language, 
this routine simply returns the same text unchanged, since for all other languages phonetic order and 
screen order are the same. 

Arguments to nlswitchbufO are: 

langid The ID number for the desired language. 

instr The character buffer in phonetic order to be converted to screen order. 

outstr The buffer in which the result of the conversion to screen order is returned, outstr 

and instr can reference the same address. 

length The length, in characters, of the buffer to be converted. 

lefttoright An unsigned short integer that specifies whether the implied primary mode of the 

data (i.e., the way it would be displayed on a terminal) is left-to-right (TRUE) or right- 
to-left (FALSE). This determines what the opposite language is and, therefore, strings 
of which characters get switched. 

err The first element of this array contains the error number. The second element is 

always zero. If the call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid string length. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

HP-UX Release 9.0: August 1992 - 1 - 667 



nlswitchbuf(3X) nlswitchbuf(3X) 



AUTHOR 

nlswitchbuf ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

Single- and multi-byte character code sets are supported. 
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NAME 

nltranslate( ) - translate ASCII strings to EBCDIC using MPE conversion table 

SYNOPSIS 

ttinclude <portnls.h> 

void nltranslate( 

short int code, 

const char * instr, 

char *outstr, 

short int length; 

short int langid, 

unsigned short int err [2], 

const char *table 
); 

DESCRIPTION 

nltranslate() translates a string of bytes from EBCDIC to ASCII or ASCII to EBCDIC, using the 
appropriate native language table. 

Arguments to nltranslate ( ) are used as follows: 

code Specifies type of conversion: 

Value Meaning 

1 Convert EBCDIC to ASCII. 

2 Convert ASCII to EBCDIC. 

instr 

Byte buffer containing the input string to be translated. 

outstr 

Byte buffer where the translated string is to be returned, instr and outstr can specify the same array. 

length 

A short integer specifying the number of bytes of instr to be translated. 

langid 

A short integer containing the ID number of the language whose translation tables are to be used. 

err 

The first element of this array contains the error number. The second element is always zero. If the 
call is successful, both elements contain zero. 

Error # Meaning 

2 Specified language is not configured. 

3 Invalid code specified. 

4 Invalid length parameter. 

table 

A 256-byte array that holds a translation table. Each byte contains the translation of the byte whose 
value is its index. This table is provided by the user. 

WARNINGS 

This routine is provided for compatibility with MPE, a proprietary HP operating system. See portnls(5) for 
more information on the use of this routine. Use the Native Language Support routines for C programmers 
described by hpnls(5) for HP-UX NLS support. 

AUTHOR 

nltranslate ( ) was developed by HP. 

SEE ALSO 

nlinfo(3X), portnls(5). 

EXTERNAL INFLUENCES 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

HP-UX Release 9.0: August 1992 - 1 - 669 



optoverhead(3N) optoverhead(3N) 



NAME 

optoverhead( ) - return number of bytes needed by a NetlPC option 

SYNOPSIS 

ttinclude <sys/ns_ipc.h> 

int optoverhead( short eventualentries, short *result); 

DESCRIPTION 

optoverhead returns the number of bytes needed by the opt parameter, excluding the data area. 

PARAMETERS 

eventualentries (input parameter) The number of option entries that will be placed in the opt parame- 

ter. 

result (output parameter) The result code returned. See "Diagnostics" below for more infor- 

mation. 

RETURN VALUE 

Upon successful completion, optoverhead () returns a 16-bit integer value indicating the number of 
bytes requires for the opt parameter, not including the data portion of the parameter. 

ERRORS 

[NSR_NO_ERROR] The call was successful. 

[NSR_OPT_TOTAL] The num_entries parameter is negative. 

AUTHOR 

optoverhead was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnam- 
erase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), 
initopt(3N), ipcerrmsg(3N), readopt(3N). 
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NAME 

perror(), strerror(), errno, sys_errlist, sys_nerr - system error messages 

SYNOPSIS 

#include <errno.h> 

void perror(const char *s); 
char *strerror (int errnum) ; 
extern int errno; 
extern char *sys_errlist [ ] ; 
extern int sys_nerr; 

DESCRIPTION 

perror ( ) writes a language-dependent message to the standard error output, describing the last error 
encountered during a call to a system or library function. The argument strings is printed first, followed by 
a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the 
name of the program that incurred the error. The error number is taken from the external variable errno, 
which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the 
message is identical to those returned by the strerror ( ) function with errno as the argument. If 
given a NULL string, the perror ( ) function prints only the message and a new-line. 

To simplify variant formatting of messages, the strerror ( ) function and the sys_errlist array of 
message strings are provided. The strerror () function maps the error number in errnum to a 
language-dependent error message string and returns a pointer to the string. The message string is 
returned without a new-line, errno can be used as an index into sys_errl is t to get an untranslated 
message string without the new-line. sys_nerr is the largest message number provided for in the table; 
it should be checked because new error codes might be added to the system before they are added to the 
table, strerror ( ) must be used to retrieve messages when translations are desired. 

EXTERNAL INFLUENCES 
Environment Variables 

The language of the message returned by strerror ( ) and printed by perror ( ) is specified by the 
LANG environment variable. If the language-dependent message is not available, or if LANG is not set or 
is set to the empty string, the default version of the message associated with the "C" language (see lang(5)) 
is used. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

perror ( ) returns no value. 

If the errnum message number is valid, strerror ( ) returns a pointer to a language-dependent message 
string. The array pointed to should not be modified by the program, and might be overwritten by a subse- 
quent call to the function. If a valid errnum message number does not have a corresponding language- 
dependent message, strerror () uses errnum as an index into sys_errlist to get the message 
string. If the errnum message number is invalid, strerror ( ) returns a pointer to a NULL string. 

SEE ALSO 

errno(2), lang(5), environ(5). 

STANDARDS CONFORMANCE 

perror ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 

strerror ( ) : AES, XPG3, XPG4, ANSI C 
sys_errlist ( ) : SVID2, XPG2 
sys_nerr ( ) : SVID2, XPG2 
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NAME 

pfm_$cleanup - establish a cleanup handler 

SYNOPSIS (C) 
C Syntax 

#include <idl/c/base.h> 
#include <ppfm.h> 

status_$t pfm_$cleanup( 

pf m_$c leanup_rec * cleanup _record ) 

Pascal Syntax 

^include '/sys/ ins /base. ins. pas' ; 
^include ' /sys / ins /ppfm. ins. pas' ; 

function pfm_$cleanup( 

out cleanup jrecord : pfm_$cleanup_rec) : status_$t; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$cleanup ( ) establishes a cleanup handler that is executed when a fault occurs. A cleanup handler 
is a piece of code executed before a program exits when a signal is received by the process. The cleanup 
handler begins where pfm_$cleanup ( ) is called; the pfm_$cleanup ( ) call registers an entry point 
with the system where program execution resumes when a fault occurs. When a fault occurs, execution 
resumes after the most recent call to pfm_$cleanup ( ) . 

There can be more than one cleanup handler in a program. Multiple cleanup handlers are executed con- 
secutively on a last-in/first-out basis, starting with the most recently established cleanup handler and end- 
ing with the first cleanup handler. 

On Apollo systems, a default cleanup handler is established at program invocation. The default cleanup 
handler is always called last, just before a program exits, and releases any system resources still held 
before returning control to the process that invoked the program. 

On other systems, there is no default cleanup handler. 

When called to establish a cleanup handler, pfm_$cleanup () returns the status 
pfm_$cleanup_set to indicate that the cleanup handler was successfully established. When the 
cleanup handler is entered in response to a fault signal, pfm_$cleanup ( ) effectively returns the value 
of the fault that triggered the cleanup handler. 

See the reference description of pfm_$init ( ) for a list of the C signals that the PFM package intercepts. 

cleanup _record Is a record of the context when pfm_$cleanup ( ) is called. A program should treat this 
as an opaque data structure and not try to alter or copy its contents. It is needed by 
pfm_$rls_cleanup ( ) and pfm_$reset_cleanup ( ) to restore the context of the calling process at 
the cleanup handler entry point. 

NOTE 

The pfm_$cleanup() call implicitly performs a pfm_$inhibit () . Cleanup handler code hence runs 
with asynchronous faults inhibited. When pfm_$cleanup( ) returns something other than 
pfm_$cleanup_set ( ) , indicating that a fault has occurred, there are four possible ways to leave the 
cleanup code: 

• The program can call pfm_$ signal ( ) to start the next cleanup handler with a fault signal you 
specify. 

• The program can call pgm_$exit() to start the next cleanup handler with a status of 
status _$ok. 

• The program can continue with the code following the cleanup handler. It should generally call 
pf m_$enable ( ) to re-enable asynchronous faults. Execution continues from the end of the 
cleanup handler code; it does not resume where the fault signal was received. 



672 - 1 - HP-UX Release 9.0: August 1992 



pfm_$cleanup(3) pfm_$cleanup(3) 



• The program can re-establish the cleanup handler by calling pfm_$reset_cleanup( ) (which 
implicitly performs a pf m_$enable ( ) ) before proceeding. 

SEE ALSO 

pfm_$init(3), pfm_$signal(3). 
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NAME 

pfm_$enable - enable asynchronous faults 

SYNOPSIS 
C Syntax 

ftinclude <idl/c/base.h> 
#include <ppfm.h> 

void pfm_$enable (void) 

Pascal Syntax 

Ssinclude ' /sys/ ins /base, ins .pas' ; 
^include ' /sys /ins /pfm. ins. pas' ; 

u2roOwdu2rs T ^f in ^snabie • 

Remarks 

To view this manual entry via the man(X) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$enable( ) enables asynchronous faults after they have been inhibited by a call to 
pf m_$inhibit ( ) ; pfm_$enable ( ) causes the operating system to pass asynchronous faults on to the 
calling process. 

While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, when 
pf m_$enable ( ) returns, there can be at most one fault waiting on the process. If more than one fault 
was received between calls to pfm_$ inhibit ( ) and pfm_$enable ( ) , the process receives the first 
asynchronous fault received while faults were inhibited. 

SEE ALSO 

pfm_$enable_faults(3), pfm_$inhibit(3). 
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NAME 

pfm_$enable_faults - enable asynchronous faults 

SYNOPSIS 
C Syntax 

#include <idl/c/base .h> 
#include <ppfm.h> 

void pfm_$enable_f aults (void) 

Pascal Syntax 

Ssinciude '' /sys/ins/base . ins .pas ' ; 
^include ' /sys/ins/pfm. ins .pas ' ; 

procedure pfm_$enable_f aults; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

The pfm_$enable_f aults ( ) call enables asynchronous faults after they have been inhibited by a call 
to pfm_$inhibit_f aults ( ) ; pfm_$enable_f aults ( ) causes the operating system to pass asyn- 
chronous faults on to the calling process. 

While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, when 
pfm_$enable_f aults ( ) returns, there can be at most one fault waiting on the process. If more than 
one fault was received between calls to pfm_$inhibit_f aults ( ) and pfm_$enable_f aults ( ) , 
the process receives the first asynchronous fault received while faults were inhibited. 

SEE ALSO 

pfm_$enable(3), pfm_$inhibit_faults(3). 
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NAME 

pfm_$inhibit - inhibit asynchronous faults 

SYNOPSIS (C) 

#include <ldl/c/base.h> 
#include <ppfm.h> 

void pfn>._$ inhibit (void) ; 

SYNOPSIS (PASCAL) 

%include '/sys /ins /base. ins. pas' ; 
^include ' /sys/ins/pfm.ins .pas ' ; 

procedure pfm_$inhibit; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$inhibit () prevents asynchronous faults from being passed to the calling process. While faults 
are inhibited, the operating system holds at most one asynchronous fault. Consequently, a call to 
pf m_$ inhibit ( ) can result in the loss of some signals. For that and other reasons, it is good practice to 
inhibit faults only when absolutely necessary. 

On systems with Concurrent Programming Support (CPS), pfm_$ inhibit () also disables time-sliced 
task switching. It does not prevent task switching due to voluntary task yielding, either explicitly via 
task_$yield ( ) or implicitly via other functions that yield. Do not use pf m_$inhibit ( ) for critical 
region concurrency control; use the mutex_ facility instead. 

See the reference description of pfm_$init ( ) for a list of the C signals that the PFM package intercepts. 

NOTE 

This call has no effect on the processing of synchronous faults such as floating-point and overflow excep- 
tions, access violations, and so on. 

SEE ALSO 

pfm_$enable(3), pfm_$inhibit_faults(3), pfm_$init(3). 

Concurrent Programming Support Reference . 
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NAME 

pfm_$inhibit_faults - inhibit asynchronous faults but allow time-sliced task switching 

SYNOPSIS 
C Syntax 

#include <idl/c/base.h> 
#include <ppfm.h> 

void pfm_$inhibit_faults(void); 

Pascal Syntax 

^include ' /sys/ ins /base. ins. pas' ; 
^include ' /sys /ins /pfm. ins. pas' ; 

procedure pfm_$inhibit_f aults ; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$inhibit_f aults ( ) prevents asynchronous faults (except for time-sliced task switching) from 
being passed to the calling process. While faults are inhibited, the operating system holds at most one 
asynchronous fault. Consequently, a call to pfm_$inhibit_f aults ( ) can result in the loss of some 
signals. For that and other reasons, it is good practice to inhibit faults only when absolutely necessary. 

See the reference description of pfm_$init ( ) for a list of the C signals that the PFM package intercepts. 

NOTE 

This call has no effect on the processing of synchronous faults such as floating-point and overflow excep- 
tions, access violations, and so on. 

SEE ALSO 

pfm_$enable_faults(3), pfm_$inhibit(3), pfm_$init(3). 
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NAME 

pfm_inhibit - pointer entry to conflicting online manual entries 

DESCRIPTION 

This manual entry is provided for accessing manual entries whose online versions have conflicting 
filenames due to maximum name length imposed by short-filename (14-character maximum) systems. 

The 



NOTE 



You have selected a name that conflicts with one or more other names. To display the manual entry 
you want, enter the man command again as follows: 



To view this entry: Use this command: 
pfm_inhibit man pfm_inhib 

pfm_inhibit_faults man pfm_inhib_f 
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NAME 

pfm_$init - initialize the process fault manager (PFM) package 

SYNOPSIS 
C Syntax 

ttinclude <idl/c/base.h> 
# include <ppfm.h> 

void pfm_$init( 

unsigned long flags) 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pf m_$init ( ) initializes the PFM package. The flags parameter indicates which initialization activities to 
perform. 

Currently, only one flags value is valid: 

pfm_$init_signal_handlers ( ) 

Intercept C signals and convert them to PFM signals. The following HP-UX signals are 
intercepted: SIGINT, SIGILL, SIGPPE, SIGTERM, SIGHUP, SIGQUIT, SIGTRAP, 
SIGBUS, SIGSEGV, and SIGSYS. On MS-DOS systems, the first four of these, plus 
SIGABRT, are intercepted. 

On Apollo systems, the PFM package does not require initialization, and pfm_$init ( ) is a no-op. On 
all other systems, applications that use the PFM package should invoke pfm_$init ( ) before invoking 
any other NCS calls. 
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NAME 

pfm_$intro - fault management 

SYNOPSIS (C) 
C Syntax 

#include <idl/c/base.h> 
#include <ppfm.h> 

Pascal Syntax 

^include ' /sys /ins /base. ins. pas' ; 
^include ' /sys / ins /ppfm. ins. pas' ; 

Remarks 

To view this manual entry via the manil) command, use the function name shown above without the "-$" 
character. 

DESCRIPTION 

pf m_$ ( ) calls allow programs to manage signals, faults, and exceptions by establishing cleanup handlers. 

NCS software products include a portable subset of the Apollo Domain/OS pfm_$ ( ) calls: 

pfm_$cleanup ( ) Establish a cleanup handler. 

pfm_$enable ( ) Enable asynchronous faults. 

pfm_$enable_f aults ( ) 

Enable asynchronous faults after faults have been inhibited via 
pf m_$inhibit_f aults ( ) . 

pfm_$inhibit ( ) Inhibit asynchronous faults. 

pfm_$inhibit_f aults ( ) 

Inhibit asynchronous faults but allow time-sliced task switching. 

pf m_$ ini t ( ) Initialize the PFM package. 

pf m_$reset_cleanup ( ) 

Reset a cleanup handler. 

pfm_$rls_cleanup ( ) 

Release cleanup handlers. 

pf m_$ s igna 1 ( ) Signal the calling process. 

Cleanup Handlers 

A cleanup handler is a piece of code that allows a program to terminate gracefully when it receives an error. 
A cleanup handler begins with a pfm_$cleanup( ) call and usually ends with a call to 
pf m_$signal ( ) or pgm_$exit ( ) , though it can also simply continue back into the program after the 
cleanup code. 

Include Files in NCS Software 

This section describes the include files for the pf m_ interface provided with NCS software. 

Version 1.1 of NCK and NIDL, contained a <pfm.h> include file that supports the std_$call ( ) calling 
convention of Apollo SR9 system software, whereby all parameters of a call are passed by reference rather 
than by value. For example, a call in C source code to pfm_$reset_cleanup( ) resembles: 

pfm_$reset_cleanup (crec, st) 

even though both crec and st are passed by reference to the implementation of 
pfm_$reset_cleanup ( ) . On Apollo SR9 systems, the C compiler treats these parameters as though 
each was preceded by the address operator &. On SunOS, ULTRIX, and VMS systems with Version 1.1 of 
NCK or NIDL, the <pfm.h> file defines macros that convert these parameters to fccrec and &st. 

In Version 1.5.1 of NCK and NIDL, a new include file for the pf m_$ ( ) calls, <ppf m. h>, is provided. This 
is the include file for the "portable PFM" interface, an interface in the style of ANSI C. When an application 
invokes a call through this interface, all output parameters must be preceded by an explicit &. For exam- 
ple, a call to pfm_$reset_cleanup() resembles: 
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pfm_$reset_cleanup (scree, &st) 

since crec and st are output parameters passed by reference. This calling convention is more natural to 
most C programmers. 

The previous include file, <pfm.h>, is still available, providing backward compatibility for programs coded 
according to the std_$call ( ) convention. However, new programs should include <ppf m. h>. 

Include Files in Apollo SR10 Domain/OS Software 

In Apollo SR10 system software, the include file <apollo/pfm.h>, defines the pfm_ interface in the 
style of ANSI C. 

Beginning at SR10.2, the file <apollo/ppfm.h>, which includes <apollo/pfm.h> is also provided; 
/usr/include/ppfm.his a symbolic link pointing to /usr/ include /apollo/ppfm.h. 

Thus, the directive 

ttinclude <ppfm.h> 

can be used both on Apollo SR10.2 systems and on other systems with Version 1.5.1 of NCK or NIDL (includ- 
ing HP-UX Releases 8.0 and 8.05). 

The signatures for pfm_$reset_cleanup ( ) and pfm_$rls_cleanup ( ) in the SR10.0 and SR10.1 
versions of <apollo/pfm.h> are incorrect. They have been corrected at SR10.2. These corrections may 
require you to modify an application developed on SR10.0 and SR10.1 Apollo systems in order to compile it 
on an SR10.2 Apollo system. See the reference descriptions of these calls for details. 

Constants 

pfm_$init_signal_handlers 

A constant used as the flags parameter to pfm_$init ( ) , causing C signals to be intercepted and 
converted to PFM signals. 

Data Types 

pf m_$c leanup_r ec 

An opaque data type for passing process context among cleanup handler calls. 

status_$t 

A status code. Most NCS calls supply their completion status in this format. The status_$t type 
is defined as a structure containing a long integer: 

struct status_$t { 
long all; 
} 

However, the calls can also use status_$t as a set of bit fields. To access the fields in a returned 
status code, assign the value of the status code to a union defined as follows: 



typedef union { 






struct { 






unsigned 


fail : 


1, 




subsys 


: 7, 




mode : 


8; 


short 


code; 




} s; 






long all; 






} status_u; 






where: 






all All 32 bits in 


the status code. 



the status was successful. 

fail If this bit is set, the error was not within the scope of the module invoked, but occurred 
within a lower-level module. 

subsys This indicates the subsystem that encountered the error. 

mode This indicates the module that encountered the error. 
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code This is a signed number that identifies the type of error that occurred. 

Status Codes 

pfm_$bad_rls_order 

Attempted to release a cleanup handler out of order. 

pf m_$ c 1 eanup_not _f ound 

iilcl" lb HI) pCHiu.Lig w^ciij.u£/ uauuici, 

pfm_$cleanup_set 

A cleanup handler was established successfully. 

pfm_$cleanup_set_signalled 

Attempted to use pfm_$cleanup_set as a signal. 

pf m_$ inval id_c leanup_rec 

Passed an invalid cleanup record to a call. 

pfm_$no_space 

Cannot allocate storage for a cleanup handler. 

status_$ok 

The call was successful. 

SEE ALSO 

pfm_$cleanup(3), pfm_$enable(3), pfm_$enable_faults(3), pfm_$inhibit(3), pfm_$mhibit_faults(3), 
pfm_$init(3), pfm_$reset_cleanup(3), pfm_$rls_cleanup(3), pfm_$signal(3). 
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NAME 

pfm_$reset_cleanup - reset a cleanup handler 

SYNOPSIS 
C Syntax 

#include <idl/c/base.h> 
ttinclude <ppfm.h> 

void pfm_$reset_cleanup( 

pf m_$c leanup_rec * cleanup jrecord, 
status_$t *status) 

Pascal Syntax 

^include ' /sys/ ins /base. ins. pas' ; 
^include ' /sys /ins /pfm. ins .pas' ; 

procedure pfm_$reset_cleanup ( 

in cleanup _record : pf m_$c leanup_rec ; 
out status : status_$t ) ; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$reset_cleanup ( ) re-establishes the cleanup handler last entered so that any subsequent errors 
enter it first. This procedure should only be used within cleanup handler code. 

A implicitly performs a thereby undoing the implicit that performs. 

cleanup jrecord A record of the context at the cleanup handler entry point. It is supplied by 
pfm_$cleanup when the cleanup handler is first established. 

status The completion status. 

NOTE 

This note concerns use of pfm_$reset_cleanup ( ) on Apollo systems. 

In the SR10.0 and SR10.1 versions of <apollo/pfm.h>, the first argument of 
pf m_$reset_cleanup ( ) is incorrectly preceded by an ampersand (&). In the SR10.2 version, the first 
argument is correctly preceded by an asterisk (*). 

Programs compiled under SR10.0 or SR10.1 will continue to run correctly, since the implementation of 
pfm_$reset_cleanup ( ) has not changed, but you may need to modify these programs in order to com- 
pile them under SR10.2. Invocations of pfm_$reset_cleanup( ) that resembled: 

pfm_$reset_cleanup(crec, &st) 
when compiled under SR10.0 and SR10.1 must be modified to 

pfm_$reset_cleanup(&crec / &st) 
when compiled under SR10.2. 
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NAME 

pfm_$rls_cleanup - release a cleanup handler 

SYNOPSIS 
C Syntax 

#include <idl/c/base.h> 
#include <ppfm.h> 

void pfm_$rls_cleanup( 

pfm_$cleanup_rec * cleanup jrecord, 
status_$t *status) 

Pascal Syntax 

^Include ■' /sys/ ins /base. ins. pas' ; 
^include ' /sys /ins /pfm. ins .pas' ; 

procedure pfm_$rls_cleanup( 

in cleanup jrecord : pf m_$c leanup_r ec ; 
out status : status_$t ) ; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$rls_cleanup ( ) releases the cleanup handler associated with cleanup_record ( ) . 

On Apollo systems, this call releases the specified cleanup handler and all cleanup handlers established 
after it. 

On other systems, this call releases only the specified cleanup handler, and only the most recently esta- 
blished cleanup handler can be released. 

If you are concerned about portability, use pfm_$rls_cleanup( ) only to release the most recent 
cleanup handler. 

cleanup _record specifies the cleanup record to be released by the cleanup handler. 

status is the completion status. 

ERRORS 

pfm_$bad_rls_order 

The caller attempted to release a cleanup handler other than the one most recently established. On 
Apollo systems, this status is only a warning; the specified cleanup handler is released, along with 
any established after it. On other systems, this status probably indicates a user programming error; 
no cleanup handlers are released, and continued execution may result in more serious errors. 

NOTE 

This note concerns use of pfm_$rls_cleanup ( ) on Apollo systems. 

In the SR10.0 and SR10.1 versions of <apollo/pfm.h>, the first argument of pfm_$rls_cleanup ( ) 
is incorrectly preceded by an ampersand (&). In the SR10.2 version, the first argument is correctly preceded 
by an asterisk (*). 

Programs compiled under SR10.0 or SR10.1 will continue to run correctly, since the implementation of 
pf m_$rls_cleanup ( ) has not changed, but you may need to modify these programs in order to compile 
them under SR10.2. Invocations of pfm_$rls_cleanup () that resembled: 

pfm_$rls_cleanup(crec / &st) 
when compiled under SR10.0 and SR10.1 must be modified to: 

pfm_$rls_cleanup(&crec, &st) 
when compiled under SR10.2. 
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NAME 

pfm_$signal - signal the calling process 

SYNOPSIS 
C Syntax 

ttinclude <idl/c/base.h> 
ttinclude <ppfm.h> 

void pfm_$signal (status_$t faultjsignal) 

C Syntax 

^include ' /sys/ins /base. ins. pas' ; 
Ssinclude ' /sys/ins /pfm. ins .pas' ; 

procedure pfm_$signal (in faultjsignal: status_^$t); 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pfm_$signal ( ) signals the fault specified by faultjsignal to the calling process. It is usually called to 
leave cleanup handlers. 

faultjsignal A fault code. 

NOTE 

This call does not return when successful. 



I 
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NAME 

pgm_$exit() - exit a program 

SYNOPSIS 
C Syntax 

#include <idl/c/base.h> 
#include <ppfm.h> 

void pgm_$exit (void) 

Pascal Syntax 

Ssinclude ' /sys/ ins /base. ins. pas' ; 
^include '/sys/ins/pgm. ins. pas' ; 

procedure pgm_$exit; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

pgm_$exi t ( ) exits from the calling program. 

Any cleanup handlers that have been established are executed in sequence from the most recently esta- 
blished to the first. 

On Apollo systems, this call invokes pf m_$slgnal ( ) with a fault code equal to the last severity level set 
by pgm_$set_sever ity ( ) , or pgm_$ok ( ) if pgm_$set_severity ( ) was not called. 

On other systems, this call invokes pf m_$signal ( ) with a fault code of status_$ok. 

SEE ALSO 

pfm_$cleanup(3), pfm_$signal(3). 
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NAME 

pgm_$intro() - program management 

SYNOPSIS 
C Syntax 

ttinclude <idl/c/base.h> 
#include <ppfm.h> 

Pascal Syntax 

^include ' /sys /ins /base. ins. pas' ; 
Ssinelude ' /sys/ins/pgia. ins .pas ' ; 

Remarks 

To view this manual entry via the man(l) command, use the function name shown above without the "$" 
character. 

DESCRIPTION 

A portable version of the Apollo Domain/OS pgm_$exit ( ) call is supplied with NCS software products. 
The include file for the "portable PFM" interface contains a declaration for this call. 



I 
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NAME 

popen(), pclose() - initiate pipe I/O to/from a process 

SYNOPSIS 

#include <stdio.h> 

PILE *popen(const char *command, const char *type) ; 
int pclose (FILE *stream) ; 

DESCRIPTION 

popen ( ) creates a pipe between the calling program and a command to be executed by the POSIX shell, 
/bin/posix/sh (see sh-posix(l)). 

The arguments to popen ( ) are pointers to null-terminated strings containing, respectively, a shell com- 
mand line and an I/O mode, either r for reading or w for writing. 

popen ( ) returns a stream pointer such that one can write to the standard input of the command if the I/O 
mode is w by writing to the file stream; and one can read from the standard output of the command if the 
I/O mode is r by reading from the file stream. 

A stream opened by popen ( ) should be closed by pclose ( ) , which waits for the associated process to 
terminate and returns the exit status of the command. 

Because open files are shared, a type r command can be used as an input filter and a type w command as 
an output filter. 

RETURN VALUE 

popen ( ) returns a NULL pointer if files or processes cannot be created. The success of the command exe- 
cution can be checked by examining the return value of pclose () . 

pclose () returns -1 if stream is not associated with a popen ()ed command, or 127 if 
/bln/poslx/sh could not be executed for some reason. 

WARNINGS 

If the original and popen ( ) ed processes concurrently read or write a common file, neither should use 
buffered I/O because the buffering will not work properly. Problems with an output filter can be forestalled 
by careful buffer flushing, e.g., with f flush ( ) ; see fclose(3S). 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). 

STANDARDS CONFORMANCE 

popen ( ) : AES, SVID2, XPG2, XPG3, XPG4, POSIX.2 

pclose ( ) : AES, SVID2, XPG2, XPG3, XPG4, POSLX.2 
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NAME 

printf(), nl_printf(), fprintfO, nl_fprintf(), sprintf(), nl_sprintf() - print formatted output 

SYNOPSIS 

#include <stdio.h> 

int printf (const char ♦format, /* [arg, ] */ ...); 

int nl_printf (const char ♦format, /* [arg,] */ ...); 

int fprintf (FILE *stream, const char *format, /* [arg,] */ ...); 

int nl_f printf (FILE *stream, const char *format, /* [arg,] */ ...}; 

int sprintf(char *s, const char *format, /* [arg,] */ ...); 

int nl_sprintf (char *s, const char *format, /* [arg,] */ ...); 

DESCRIPTION 

printf () and nl_printf () place output on the standard output stream stdout. 

fprintfO and nl_f printf () place output on the named output stream. 

sprintf () and nl_sprintf () place "output", followed by the null character (\0), in consecutive 
bytes starting at *s. It is the user's responsibility to ensure that enough storage is available. 

Each function converts, formats, and prints its args under control of the format, format is a character 
string containing two types of objects: plain characters that are copied to the output stream, and conver- 
sion specifications, each of which results in fetching zero or more args. The results are undefined if there 
are insufficient args for the format. If the format is exhausted while args remain, excess args are ignored. 

Each conversion specification is introduced by the character % or %n$, where n is a decimal integer in the 
range 1 through {NL_ARGMAX} (NL_ARGMAX is defined in <limits.h>). The %n$ construction indi- 
cates that this conversion should be applied to the nth argument, rather than to the next unused one. 

An argument can be referenced by a %n$ specification more than once. The two forms of introducing a 

conversion specification, % and %n$, cannot be mixed within a single format string. Improper use of %n $ _ 

in a format string results in a negative return value. I 

After the % or %n $, the following appear in sequence: 

1. Zero or more flags, which modify the meaning of the conversion specification. 

2. An optional string of decimal digits to specify a minimum field width in bytes. If the converted 
value has fewer characters than the field width, it is be padded on the left (or right, if the left- 
adjustment flag (-), described below, has been given) to the field width. If the field width is pre- 
ceded by a zero, the string is right adjusted with zero-padding on the left (see the leading-zero 
flag (0) described below). 

3. A precision that gives the minimum number of digits to appear for the d, i, o, u, x, or X conver- 
sions, the number of digits to appear after the radix character for the e and f conversions, the 
maximum number of significant digits for the g conversion, or the maximum number of bytes to 
be printed from a string in the s conversion. The precision takes the form of a period (.) fol- 
lowed by a decimal digit string; a null digit string is treated as zero. 

4. An optional 1 (the letter "ell"), specifying that a following d, i, o, u, x, or X conversion charac- 
ter applies to a long integer arg; an optional 1 specifying that a following n conversion charac- 
ter applies to a pointer to a long integer arg; an optional h, specifying that a following d, i, o, u, 
x, or X conversion character applies to a short integer arg; an optional h specifying that a fol- 
lowing n conversion character applies to a pointer to a short integer arg; an optional L specify- 
ing that a following e, E, f , g, or G conversion character applies to a long double arg. An 1, h 
or L before any other conversion character is ignored. 

5. A conversion character that indicates the type of conversion to be applied. 

A field width or precision can be indicated by an asterisk (*) instead of a digit string. In this case, an 
integer arg supplies the field width or precision. The arg that is actually converted is not fetched until 
the conversion letter is seen, so the args specifying field width, or precision, or both must appear in that 
order before the arg, if any, to be converted. A negative field width is taken as a - flag followed by a 
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positive field width. A negative precision is taken as if the precision were omitted. Format strings con- 
taining %n$ conversion specifications can also indicate a field width or precision by the sequence *n$. 
The n indicates the position of an integer arg. With the *n$ sequence, the args specifying field width or 
precision can appear before or after the arg to be converted. 

The flag characters and their meanings are: 

The resulting conversion is left-justified within the field. 

+ The resulting signed conversion always begins with a sign (+ or -). 

blank If the first character of a signed conversion is not a sign, a blank is prefixed to the result. 
This implies that if the blank and + flags both appear, the blank flag is ignored. 

# This flag specifies that the value is converted to an "alternate/brm". For c, d, i, s, n, 

and u conversions, the flag has no effect. For o conversion, it increases the precision to 
force the first digit of the result to be a zero. For x or X conversion, a non-zero result 
has Ox or OX prefixed to it. For a p conversion, a non-zero result has Ox prefixed to 
it. For e, E, f , g, and G conversions, the result always contains a radix character, even 
if no digits follow the radix (normally, a radix character appears in the resulting conver- 
sions only if followed by a digit). For g and G conversions, trailing zeroes are not 
removed from the result (which they normally are). 

Leading zeros (following any indication of sign or base) are used to pad to the field width 

for all conversion characters. No space padding is performed. If both the and - 
appear, the flag is ignored. For d, i, o, u, p, x, and X, conversions, if a precision is 
specified, the flag is ignored. 

The conversion characters and their meanings are: 

d,i,o,u,x,X The integer arg is converted to signed decimal (d and i are identical), unsigned 
octal (o), decimal (u), or hexadecimal notation (x and X), respectively; the letters 
abcdef are used for x conversion and the letters ABCDEP for X conversion. The 
precision specifies the minimum number of digits to appear; if the value being con- 
verted can be represented in fewer digits, it is expanded with leading zeroes. (For 
compatibility with older versions, padding with leading zeroes can alternatively be 
specified by inserting a zero in front of the field width. This does not imply an octal 
value for the field width.) The default precision is 1. The result of converting a 
zero value with a precision of zero is a null string. 

f The double arg is converted to decimal notation in the style [-]dddrddd, where r 

is the radix character. The number of digits after the radix character is equal to 
the precision specification. If the precision is missing, six digits are output. If the 
precision is explicitly zero, no radix character appears. 

e,E The double arg is converted in the style [-]drddde±ddd where r is the radix 

character. There is one digit before the radix character and the number of digits 
after it is equal to the precision; when the precision is missing, six digits are pro- 
duced; if the precision is zero, no radix character appears. The E format code pro- 
duces a number with E instead of e introducing the exponent. The exponent 
always contains at least two digits. 

g,G The double arg is printed in style f or e (or in style E in the case of a G format 

code), with the precision specifying the number of significant digits. The style used 
depends on the value converted: style e is used only if the exponent resulting from 
the conversion is less than -4 or greater than or equal to the precision. Trailing 
zeroes are removed from the fractional part of the result; a radix character appears 
only if it is followed by a digit. 

c The int arg is converted to an unsigned char, and the resulting character is printed. 

C The wchar_t arg is converted to an array of bytes representing the single wide 

character according to the setting of LC_CTYPE. Resulting bytes are printed. If 
the precision is given, it is ignored. If the field width would otherwise cause the 
wide character to be split, the wide character is printed and the field width is 
adjusted upward. 
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s The arg is taken to be a string (character pointer) and characters from the string 

are printed until a null character (\ 0) is encountered or the number of bytes indi- 
cated by the precision specification is reached. If the precision is missing, it is 
taken to be infinite, so all characters up to the first null character are printed. A 
NULL value for arg yields undefined results. 

S The arg is taken to be a pointer to a wide character string (wchar_t *). Wide 

characters from the string are converted to an array of bytes representing the 
string of wide characters according to the setting of LC_CTYPE. Resulting bytes 
are printed until a null wide character ( (wchar_t ) 0) is encountered or the 
number of bytes indicated by the precision is reached. If the precision is missing, it 
is taken to be infinite, so all wide characters up to the first null wide character are 
printed. If the field width would otherwise cause the last multibyte character to be 
split, the last wide character is not printed. A NULL value for arg yields undefined 
results. 

p The value of a pointer to void arg is printed as a sequence of unsigned hexadecimal 

numbers. The precision specifies the minimum number of digits to appear; if the 
value being converted can be represented in fewer digits, it is expanded with lead- 
ing zeroes. The default precision is 1. The result of converting a zero value with a 
precision of zero is a null string. 

n A pointer to an integer arg is expected. This pointer is used to store the number of 

bytes printed on the output stream so far by this call to the function. No argument 
is converted. 

% Print a %\ no argument is converted. 

In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion 
is wider than the field width, the field is expanded to contain the conversion result. 

Characters generated by printf ( ) , f printf ( ) , nl_printf ( ) , and nl_f printf ( ) are printed 
as if putc ( ) had been called (seeputc(SS)). 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category affects the following features: 

• Plain characters within format strings are interpreted as single and/or multi-byte characters. 

• Field width is given in terms of bytes. As characters are placed on the output stream they are 
interpreted as single or multi-byte characters and the field width is decremented by the length of 
the character. 

• Precision is given in terms of bytes. As characters are placed on the output stream, they are inter- 
preted as single or multi-byte characters and the precision is decremented by the length of the 
character. 

• The return value is given in terms of bytes. As characters are placed on the output stream, they 
are interpreted as single or multi-byte characters and the byte count that makes up the return 
value is incremented by the length of the character. 

The LC_NUMERIC category determines the radix character used to print floating-point numbers. 

International Code Set Support 

Single-byte character code sets are supported. Multi-byte character code sets are also supported as 
described in the LC_CTYPE category above. 

RETURN VALUE 

Each function returns the number of bytes transmitted (excluding the \0 in the case of sprintf ( ) and 
nl_spr intf ( ) ), or a negative value if an output error was encountered. Improper use of %n $ in a for- 
mat string results in a negative return value. 

ERRORS 

printf ( ) , f printf ( ) , nl_print f ( ) , and nl_f printf ( ) fail if either the stream is unbuffered or 
stream's buffer needed to be flushed causing an underlying write ( ) call to be invoked (see write(2)\ and: 
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[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the 

maximum file size (see ulimit(2)). 

LEINTR] A signal was caught during the wr ite ( ) system call. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any pro- 

cess. A S I GP I PE signal is also sent to the process. 

Additional errno values can be set by the underlying write () function (see write(2)). 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02", where weekday and month are pointers to 
null-terminated strings: 

printf ("%s, %& %d, %d:%.2d", weekday, month, day, hour, min) ; 

To print n to 5 decimal places: 

printfC'pi = %.5f", 4 * atan(l.O)); 
To create a language-independent date-and-time printing routine write: 

printf(format,weekday,month,day,hour,min,2,2); 
For American usage, format would point to the string: 

"%l$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d" 
and result in the output: 

"Sunday, July 3, 10:02" 
For German usage, the string: 

"%l$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d" 
results in the output: 

Sonntag, 3 Juli 10:02 

WARNINGS 

nl_prlntf ( ) , nl_f print f ( ) , and nl_sprintf ( ) are provided for historical reasons only. Their 
use is not recommended. Use print f ( ) , f print f ( ) , and sprint f ( ) instead. 

Notice that with the c conversion character, an int arg is converted to an unsigned char. Hence, whole 
multi-byte characters cannot be printed using a single c conversion character. 

A precision with the s conversion character might result in the truncation of a multi-byte character. 

AUTHOR 

printf(), fprintf(), and sprintf() were developed by AT&T and HP. nl_printf(), 
nl_f printf ( ) , and nl_sprintf ( ) were developed by HP. 

SEE ALSO 

ecvt(3C), setlocale(3C), putc(3S), scanf(3S), stdio(3S). 

STANDARDS CONFORMANCE 

printf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
f printf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

nl_f printf ():XPG2 
nl_printf ():XPG2 
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nl_sprintf ( ) : XPG2 

sprintf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

printmsgO, fprintmsg(), sprintmsg() - print formatted output with numbered arguments 

SYNOPSIS 

#include <stdio.h> 

int printmsg (const char ♦format, /* [arg, ] */ ...); 

int fprintmsg(FILE *stream, const char *format, /* [arg, ] */ ...); 

int sprintmsg(char *s, const char *format, /* [arg, ] */ ...); 

DESCRIPTION 

printmsg ( ) , f printmsg ( ) , and sprintmsg ( ) are derived from their counterparts in the printf(3S) 
manual entry. The conversion character % can be replaced by %digits$. digits are decimal digits 
representing a number n in the range (1 - {NL_ARGMAX}) (NL_ARGMAX is defined in <limits .h>), and 
indicates that this conversion should be applied to the nth argument, rather than to the next unused one. 
All other aspects of formatting are unchanged. All conversion specifications must contain the %digits$ 
sequence and the user must ensure correct numbering. All parameters must be used exactly once. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category affects the following features: 

• Plain characters within format strings are interpreted as single and/or multi-byte characters. 

• Field width is given in terms of bytes. As characters are placed on the output stream, they are 
interpreted as single or multi-byte characters and the field width is decremented by the length of 
the character. 

• Precision is given in terms of bytes. As characters are placed on the output stream, they are inter- 
preted as single or multi-byte characters and the precision is decremented by the length of the 
character. 

• The return value is given in terms of bytes. As characters are placed on the output stream, they 
are interpreted as single- or multi-byte characters and the byte count that makes up the return 
value is incremented by the length of the character. 

The LC_NUMERIC category determines the radix character used to print floating-point numbers. 

International Code Set Support 

Single-byte character code sets are supported. Multi-byte character code sets are also supported as 
described in the LC_CTYPE category above. 

EXAMPLES 

To create a language-independent date and time printing routine, use 

printmsg (format, weekday, month, day, hour, min) ; 
For American usage format would point to the string: 

%l$s, %2$s %3$d, %4$d:%5$.2d 
resulting in the output: 

Sunday, July 3, 10:02 
For German usage, the string: 

%l$s, %3$d %2$s %4$d:%5$.2d 
results in the following output: 

Sonntag, 3 Juli 10:02 
provided the proper strings have been read. 

WARNINGS 

These routines are provided for historical reasons only. Use of the printf(3S) equivalent routines printf , 
f printf ( ) , and sprintf ( ) is recommended. 
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AUTHOR 

printmsg ( ) was developed by HP. 

SEE ALSO 

catgetmsg(3C), setlocale(3C), printft3S), hpnls(5). 



I 
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NAME 

ptsname - get the name of a slave pty 

SYNOPSIS 

char *ptsname(int fildes); 

Remarks: 

pt sname ( ) is useful only on systems that follow the insf(lM) naming conventions for ptys. 

DESCRIPTION 

The passed parameter, fildes, is a file descriptor of an opened master pty. ptsname ( ) generates the 
name of the slave pty corresponding to this master pty. This means that their minor numbers will be the 
same. 

RETURN VALUE 

Upon successful completion, ptsname ( ) returns a string containing the the full path name of a slave pty. 
Otherwise, a NULL pointer is returned. The return value may point to static data which is overwritten with 
each call to ptsname ( ) , so it should be copied if it is to be saved. 

ERRORS 

ptsname ( ) fails and returns a NULL pointer under the following conditions: 

• File descriptor does not refer to an open master pty. 

• Request falls outside pty name-space. 

• Pty device naming conventions have not been followed. 

• pt sname ( ) failed to find a match. 

EXAMPLES 

The following example gets the path of a slave pty corresponding to a master pty obtained through a pty 
clone open. 

int fd_master; 
char *path; 

fd_master = open ("/dev/ptym/ clone", 0_RDONLY) ; 
path = ptsname (fd_master) ; 

AUTHOR 

ptsname ( ) was developed by HP. 

SEE ALSO 

insf(lM), devnm(3), pty(7). 
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NAME 

putc(), putchar(), fputc(), putw( ) - put character or word on a stream 

SYNOPSIS 

ttinclude <stdio.h> 

int putc(int c, PILE *stream) ; 
int putchar ( int c ) ; 
int fputc(int c, PILE *stream) ; 
int putw(int w, PILE *stream) ; 

DESCRIPTION 

putc ( ) Writes the character c onto the output stream at the position where the file pointer, if 

defined, is pointing, putchar (c) is defined as putc(c, stdout). putc ( ) and 
putchar ( ) are defined both as macros and as functions. 

f putc ( ) Same as putc ( ) , but is a function rather than a macro, and can therefore be used as an 

argument, f putc ( ) runs more slowly than putc ( ) , but takes less space per invoca- 
tion, and its name can be passed as an argument to a function. 

putw( ) Writes the word (i.e., int in C) w to the output stream (at the position at which the file 

pointer, if defined, is pointing). The size of a word is the size of an integer and varies from 
machine to machine, putw ( ) neither assumes nor causes special alignment in the file. 

Output streams, with the exception of the standard error stream stderr, are by default buffered if the 
output refers to a file and line-buffered if the output refers to a terminal. The standard error output 
stream, stderr, is by default unbuffered, but use of f reopen () (see fopen(3S)) causes it to become 
buffered or fine-buffered, setbuf ( ) or setvbuf ( ) (see setbuf(3S)) can be used to change the stream's 
buffering strategy. 

RETURN VALUE 

On success, putc ( ) , f putc ( ) , and putchar ( ) each return the value they have written. On failure, 
they return the constant EOF, set the error indicator for the stream, and set er mo to indicate the error. 

On success, putw ( ) returns 0. Otherwise, a non-zero value is returned, the error indicator for the stream 
is set, and errno is set to indicate the error. 

ERRORS 

putc ( ) , putchar ( ) , f putc ( ) , and putw ( ) fail if, either the stream is unbuffered or stream's buffer 
needed to be flushed causing an underlying write ( ) call to be invoked, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the 

maximum file size (see ulimit(2)). 

IEINTR] A signal was caught during the write () system call. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any pro- 

cess. A SIGPIPE signal is also sent to the process. 

Additional errno values can be set by the underlying write ( ) function (see write(2)). 

WARNINGS 

The putc ( ) and putchar ( ) routines are implemented as both library functions and macros. The 
macro versions, which are used by default, are defined in <stdio.h>. To obtain the library function 
either use a ttundef to remove the macro definition or, if compiling in ANSI-C mode, enclose the function 
name in parentheses or use the function address. The following example illustrates each of these methods: 
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ttinclude <stdio.h> 
#undef putc 

main() 
{ 

int ( *put_char ( ) ) ( ) ; 

return_val=putc (c, fd) ; 

return_val=(putc) (c,fdl) ; 

put_char = put char; 
} ; 

Line buffering may cause confusion or malfunctioning of programs that use standard I/O routines but use 
read ( ) themselves to read from standard input. When a large amount of computation is done after print- 
ing part of a line on an output terminal, it is necessary to f flush ( ) (see fclose(3S)) the standard output 
before beginning the computation. 

The macro version of putc ( ) incorrectly treats the argument stream with side effects. In particular, the 
following call may not work as expected: 

putc(c, *f++); 

The function version of putc ( ) or f putc ( ) should be used instead. 

Because of possible differences in word length and byte ordering, files written using putw( ) are machine- 
dependent, and may not be readable by getw ( ) on a different processor. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). 

STANDARDS CONFORMANCE 

putc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
f putc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

putchar ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
putw ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

putenv( ) - change or add value to environment 

SYNOPSIS 

ttinclude <stdlib.h> 

int putenv (const char *string) ; 

DESCRIPTION 

string points to a string of the form name=value. putenv ( ) makes the value of the environment vari- 
able name equal to value by altering an existing variable or creating a new one. In either case, the string 
pointed to by string becomes part of the environment, so altering the string changes the environment. The 
space used by string is no longer used once a new string-defining name is passed to putenv ( ) . 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of characters in string as single- and/or multi-byte 
characters. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

DIAGNOSTICS 

putenv () returns non-zero if it was unable to obtain enough space via malloc() for an expanded 
environment; otherwise it returns zero. 

WARNINGS 

putenv ( ) manipulates the environment pointed to by environ, and can be used in conjunction with 
getenv ( ) . However, envp (the third argument to main) is not changed. 

This routine uses ma Hoc ( ) to enlarge the environment (see malloc(3C)). 

After putenv ( ) is called, environmental variables are not in alphabetical order. 

A potential error is to call putenv ( ) with an automatic variable as the argument, then exit the calling 

function while string is still part of the environment. H 

SEE ALSO ^ 

exec(2), getenv(3C), malloc(3C), environ(5). 

STANDARDS CONFORMANCE 

putenv ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

putpwent( ) - write password file entry 

SYNOPSIS 

# include <pwd.h> 

int putpwent (const struct passwd *p, PILE *f); 

DESCRIPTION 

putpwent ( ) is the inverse of getpwent ( ) (see getpwent(3C)). Given a pointer to a passwd structure 
as created by getpwent ( ) (or getpwuid() or getpwnamO), putpwent () writes a line on the 
stream/", which matches the format of /etc /passwd. 

putpwent ( ) ignores the audit ID and audit flag in the passwd structure; and does not create the 
corresponding entries used in the secure password file (/. secure/etc/passwd). putspwent() 
which produces entries that match the secure password file format, must be used to create these entries. 

DIAGNOSTICS 

putpwent ( ) returns non-zero if an error was detected during its operation; otherwise it returns zero. 

SEE ALSO 

getpwent(3C), putspwent(3C), passwd(4), spasswd(4). 

STANDARDS CONFORMANCE 

putpwent ( ) : SVID2, XPG2 
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NAME 

puts(), fputs() - put a string on a stream 

SYNOPSIS 

ttinclude <stdio.h> 

int puts (const char *s); 

int fputs (const char *s, FILE *stream) ; 

DESCRIPTION 

puts ( ) writes the null -terminated strin CT pointed to by s followed b v a new-line character, to the- standard 
output stream stdout. 

fputs ( ) writes the null-terminated string pointed to by s to the named output stream, but does not 
append a new-line character. 

Neither function writes the terminating null character. 

RETURN VALUE 

Upon successful completion, puts() and fputs () return a non-negative number. Otherwise they 
return EOF, set the error indicator for the stream, and set errno to indicate the error. 

ERRORS 

puts ( ) and fputs ( ) fail if, either the stream is unbuffered or stream's buffer needed to be flushed caus- 
ing an underlying write ( ) call to be invoked, and: 

[EAGAIN] The flag is set for the file descriptor underlying stream and the process would be 

delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the 

maximum file size (see ulimit{2)). 

[EINTR] A signal was caught during the write ( ) system call. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any pro- 

cess. A SIGPIPE signal is also sent to the process. 

Additional errno values may be set by the underlying write () function (see write(2)). 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S). 

NOTES 

puts() appends a new-line character; fputs () does not. 

STANDARDS CONFORMANCE 

puts ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSDL1, ANSI C 

fputs ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

putspwent() - write secure password file entry 

SYNOPSIS 

#include <pwd.h> 

int putspwent (const struct s_passwd *p, PILE *f); 

DESCRIPTION 

putspwent ( ) is the inverse of getspwent () (see getspwent(SC)). Given a pointer to a s_passwd 
structure, as created by getspwent ( ) , putspwent ( ) writes a line on the stream/", which matches the 
format of / . secure/etc/passwd. 

RETURN VALUE 

putspwent ( ) returns non-zero if it detects an error during its operation; otherwise it returns a value of 
zero. 

AUTHOR 

putspwent ( ) was developed by HP. 

SEE ALSO 

getpwent(3C), getspwent(3C), putpwent(3C), spasswd(4). 
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NAME 

putwc(), putwchar(), fputwcO - put a wide character on a stream file 

SYNOPSIS 

#include <wchar.h> 

wint_t putwc (wint_t wc, PILE *stream); 

wint_t putwchar (wint_t wc); 

wint_t f putwc (wint_t wc, PILE *stream) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. 
They parallel the 8-bit character I/O functions defined in putc(3S) . 

DESCRIPTION 

putwc ( ) Writes the character corresponding to the wide character wc onto the output stream at the 

position where the file pointer is pointing, putwchar (wc) is defined as putwc (wc, 
stdout ) . putwc ( ) and putwchar ( ) are defined both as macros and as functions. 

f putwc ( ) Behaves like putwc ( ) , but is a function rather than a macro, and can therefore be used as 
an argument. 

Output streams, with the exception of the standard error stream stderr, are by default buffered if the 
output refers to a file and line-buffered if the output refers to a terminal. The standard error output 
stream, stderr, is by default unbuffered, but use of freopenO (see fopen(SS)) causes it to become 
buffered or line-buffered, setbuf ( ) or setvbuf ( ) (see setbuf(3S)) can be used to change the stream's 
buffering strategy. 

Definitions for these functions, the type wintjt and the value WEOF are provided in the <wchar.h> 
header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

On success, putwc ( ) , f putwc ( ) , and putwchar ( ) each return the wide character corresponding to 
the value they have written. On failure, they return the constant WEOF, set the error indicator for the 
stream, and set errno to indicate the error. 

ERRORS 

putwc ( ) , putwchar ( ) , and f putwc ( ) fail if either the stream is unbuffered, or stream's buffer needed 
to be flushed causing an underlying wr it e ( ) call to be invoked, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the pro- 

cess would be delayed in the write operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the 

maximum file size (see ulimit(2)). 

[EINTR] A signal was caught during the wr ite ( ) system call. 

[EIO] The process is in a background process group and is attempting to write to its control- 

ling terminal, TOSTOP is set, the process is neither ignoring nor blocking the 
SIGTTOU signal, and the process group of the process is orphaned. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any pro- 

cess. A SIGPIPE signal is also sent to the process. 

[EILSEQJ The wide character wc does not correspond to a valid character. 
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Additional errno values can be set by the underlying write ( ) function (see write(2)). 

WARNINGS 

putwc ( ) and putwchar ( ) are implemented both as library functions and as macros. The macro ver- 
sions, which are used by default, are defined in <wchar .h>. To obtain the library function either use a 
#undef to remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in 
parentheses or use the function address. The following example illustrates each of these methods: 

ttlnclude <wchar.h> 
ttundef putwc 

main() 
{ 

wint_t ( *put_wchar ( ) ) ( ) ; 

return_val=putwc (wc, fd) ; 

return_val= (putwc) (wc, fdl) ; 

put_wchar = putwchar; 
}; 

Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but 
use read ( ) themselves to read from standard input. When a large amount of computation is done after 
printing part of a line on an output terminal, it is necessary to f flush ( ) (see fclose(3S)) the standard 
output before beginning the computation. 

The macro version of putwc ( ) incorrectly treats the argument stream with side effects. In particular, the 
following call may not work as expected: 

putwc (wc, *f++); 

The function version of putwc ( ) or f putwc ( ) should be used instead. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). 

STANDARDS CONFORMANCE 

putwc ( ) : XPG4 

f putwc ( ) : XPG4 
putwchar ( ) : XPG4 
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NAME 

qsort() - quicker sort 

SYNOPSIS 

ttinclude <stdlib.h> 

void qsort ( 

void *base, 

size_t nel, 

size_t size, 

int (*compar) (const void *, const void *) 
); 

DESCRIPTION 

qsort ( ) is an implementation of the quicker-sort algorithm. It sorts a table of data in place. 

base Pointer to the element at the base of the table. 

nel Number of elements in the table. 

size Size of each element in the table. 

compar Name of the comparison function, which is called with two arguments that point to the 

elements being compared. The function passed as compar must return an integer less 
than, equal to, or greater than zero, according to whether its first argument is to be con- 
sidered less than, equal to, or greater than the second. strcmp( ) uses this same 
return convention (see strcmp(3C)). 

NOTES 

The pointer to the base of the table should be of type pointer-to-element, and cast to type pointer-to-void. 

The comparison function need not compare every byte; thus, arbitrary data can be contained in the ele- 
ments in addition to the values being compared. 

The order in the output of two items which compare as equal is unpredictable. 

SEE ALSO 

sort(l), bsearch(3C), lsearch(3C), string(3C). 

WARNINGS 

If size is zero, a divide-by-zero error might be generated. 

STANDARDS CONFORMANCE 

qsort ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

rand( ), srand( ) - simple random-number generator 

SYNOPSIS 

#include <stdlib.h> 

int rand (void) ; 

void s rand (unsigned int seed); 
DESCRIPTION 

32 

rand ( ) uses a multiplicative, congruential, random-number generator with period 2 that returns succes- 
sive pseudo-random numbers in the range from to 2 15 -1. 

srand ( ) can be called at any time to reset the random-number generator to a random starting point. The 
generator is initially seeded with a value of 1. 

NOTE 

The spectral properties of rand ( ) leave a great deal to be desired. drand4 8 ( ) provides a much better, 
though more elaborate, random-number generator (see drand48(SC)). 

SEE ALSO 

drand48(3C). 

STANDARDS CONFORMANCE 

rand ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

srand ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

rcmd(), rresvport(), ruserok() - return a stream to a remote command 

SYNOPSIS 

int rcmd ( 

char **ahost, 
unsigned short inport, 
const char *locuser, 
const char *remuser, 
const char *cmd, 
int *f d2p) ; 

int rresvport ( int *port); 

int ruserok ( 

const char *rhost, 
int superuser, 
const char *ruser, 
const char *luser) ; 

DESCRIPTION 

rcmd ( ) A routine used by privileged programs to execute cmd on the remote host *ahost 

using an authentication scheme based on reserved port numbers. rcmd( ) returns 
a file descriptor for the socket to which the standard input and standard output of 
cmd are attached. A command level interface to rcmd ( ) is provided by remsh (see 
remsh(l)), which is the same command as BSD rsh. 

rresvport ( ) Returns a descriptor to a socket with an address in the privileged port space. 

ruserok ( ) Used by servers to authenticate clients requesting service with rcmd ( ) . 

Any program using rcmd() or rresvport ( ) must be run as super-user. 

The name of the remote host can be either an official host name or an alias as understood by gethost- 
byname ( ) ; (see gethostent(SN), named(lM.), and hosts(4)). rcmd ( ) looks up the host *ahost using 
gethostbyname( ), returning -1 if the host does not exist. Otherwise *ahost is set to the standard 
name of the host and a connection is established to a server residing at the Internet port inport. If the con- 
nection is refused after five tries, or if it was refused for a reason other than the port being in use, rcmd ( ) 
returns -1. 

If the call succeeds, a socket of type SOCKJ3TREAM is returned to the caller, and given to the remote com- 
mand as stdin and stdout. If fd2p is non-zero, an auxiliary connection to a control process is set up, 
and a descriptor for it is placed in *fd2p. The control process returns diagnostic output from the command 
on this connection, and also accepts bytes on this connection as UNIX signal numbers, to be forwarded to the 
process group of the command. If the auxiliary port cannot be set up, rcmd( ) returns -1. \ifd2p is 0, 
stderr of the remote command is made the same as stdout, and no provision is made for sending arbi- 
trary signals to the remote process. 

The protocol is described in detail by remshd(lM). 

rresvport ( ) is used to obtain a socket with a privileged address bound to it. This socket is suitable 

for use by rcmd ( ) and several other routines. Privileged addresses consist of a port 
in the range to 1023. Only the super-user is permitted to bind an address of this 
sort to a socket. 

ruserok () verifies that ruser on rhost is authorized to act as luser on the local host. The 

superuser parameter to ruserok ( ) is an integer flag that should be non-zero if the 
local user name corresponds to the super-user. If the superuser flag is not set, 
ruserok ( ) first checks the file /etc/hosts . equiv to authenticate the request 
for service. If this check succeeds, ruserok ( ) returns 0. If the superuser flag is 
set, or if there is no file /etc/hosts . equiv, or if the check fails, ruserok ( ) 
then checks a file .rhosts (if there is one) in the local user's home directory, 
ruserok () returns if this check succeeds. Otherwise it returns -1. 

Typically, the file /etc/hosts .equiv contains a list of host names, and users' 
.rhosts files contain host-name/user-name pairs. A remote user is authenticated 
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by ruserok ( ) if the remote host name appears in /etc/hosts . equiv and the 
remote user name and local user name are the same, or if the remote host name and 
the remote user name appear together in . rhosts in the home directory of the local 
user. 

For a complete explanation of the syntax understood by ruserokO, see 
hosts.eguiv(4). 

DIAGNOSTICS 

rcmd Diagnostic Messages 

rcmd ( ) returns the following diagnostic messages: 

hostname : Unknown host 

gethostbyname was unable to find an entry in the hosts database matching the name of the 
server (see gethostent(3N) and hosts(4)). 

Next step: Have the system administrator of your host check whether the remote host's entry is 
in the hosts database (see hosts(4)). 

connect : hostname : ... 

Unable to establish a connection to the reserved port. A message that specifies the reason for 
the failure is appended to this diagnostic message. 

write: Setting up stderr 

Error writing to the socket connection set up for error message transmission. 

system call : . . . 

Error executing the system call. Appended to this error is a message specifying the reason for 
the failure. 

socket: Protocol failure in circuit setup 

Socket connection not established on a reserved port or socket address not of the Internet family 
type. 

read : hostname : ... 

Error in reading information from the standard socket connection. Appended to this error is a 
message explaining the reason for the error. 

Connection timeout 

The remote host did not connect within 30 seconds to the secondary socket set up as an error 
connection. 

Lost connection 

The program attempted to read from the socket and failed. This means the socket connection 
with the remote host was lost. 

message... 

An error message can be transmitted through the socket connection from the daemon. That 
message will be sent to stderr. 

primary connection shutdown 

While waiting for the secondary socket to be set up, rcmd ( ) had its primary connection shut 
down. This may have been caused by an inetd security failure. 

recv: . . . 

While trying to set up the secondary (stderr) socket, rcmd ( ) had an error condition on its 
primary connection. 

accept: Interrupted system call 

While trying to set up its secondary socket, rcmd ( ) ran out of some resource that caused the 
accept to be timed out. 

Next step: Repeat the command. 

rcmd and rresvport Diagnostic Messages 

The diagnostic messages associated with rresvport ( ) can also appear in rcmd( ) since rcmd( ) calls 
rresvport ( ) : 
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system call : . . . 

Error in executing the system call. The error message returned by the system call is appended 
to the message. 

socket: All ports in use 

All reserved ports in use. If a timeout occurs, check whether the ARPA Services are installed and 
lnetd is running. 

EXAMPLES 

To execute the date command on remote host hpxzgy usmg the remote account chm, use rcmd() as 
shown below. This program requires super-user privileges, and the remote account must be equivalent (see 
hosts.equiv(4)) to the local account that runs the program. 

#include <sys/types.h> 
#lnclude < sys/ socket .h> 
#lnclude <netinet/in.h> 
#include <netdb.h> 
#include <stdio.h> 
ttinclude <pwd.h> 

struct passwd *getpwuid(); 
char *host[] = { "hpxzgy" }; 
char *cmd = "date"; 
char *ruser = "chm"; 

main (argc, argv) 

lnt argc; 

char **argv; 
{ 

struct servent *sp; 

struct passwd *pwd; 

FILE *fp; 

char ch; 

lnt rem; 

sp = getservbyname ( "shell" , "tcp") ; 

pwd = getpwuid(getuid( ) ) ; 

rem = rcmd(host, sp->s_port, pwd->pw_name, ruser, cmd, 0); 

if (rem < 0) 

exit(l); /* rcmd outputs its own error messages */ 
fp = fdopen(rem, "r"); 
while ((ch = getc(fp)) != EOF) 

put char (ch) ; 
} 

WARNINGS 

There is no way to specify options to the socket ( ) call that rcmd ( ) makes. Since rcmd ( ) replaces 
the pointer to the hostname (*ahost) with a pointer to the standard name of the host in a static data area, 
this value must be copied into the user's data area if it is to be used later. Otherwise unpredictable results 
will occur. 

AUTHOR 

rcmd ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

login(l), rlogin(l), remsh(l), named(lM), remshd(lM), rexecd(lM), gethostent(3N), rexec(3N), 
hosts.equiv(4). 
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NAME 

readopt( ) - obtain option code and data from NetlPC option buffer 

SYNOPSIS 

ttinclude <sys/ns__ipc .h> 

void readopt ( 

short- opt [ ] i 
short argnum, 
short *optioncode, 
short *datalength, 
short data [ ] , 
short *result); 

DESCRIPTION 

readopt ( ) extracts an option from an option buffer and copies it into a user-supplied data buffer. 

readopt ( ) recognizes the following parameters: 

opt (input parameter) The opt parameter to be read. 

argnum (input parameter) The number of the argument to be obtained. The first argument is 

number zero. 

optioncode (output parameter) The option code or constant definition (C programs only) associ- 

ated with the argument. These codes are described in each NetlPC call opt parameter 
description. 

datalength (input/output parameter) The length of the data buffer into which the argument 
should be read. On output, this parameter contains the length of the data actually 
read. The length of the data associated with a particular option code is provided in 
each NetlPC call opt parameter description. 

data (output parameter) A data buffer which will contain the data read from the argument. 

result (output parameter) The result code returned. Refer to "Diagnostics" below for more 

information. 

RETURN VALUE 

None. Errors are returned in the result parameter. 

ERRORS 

readopt ( ) fails and sets result to the value indicated if any of the following conditions are encountered: 

[NSR_ADDR_OPT] The opt buffer pointer is null. 

[NSR_NO_ERROR] The call was successful. 

[NSR_OPT_CANTREAD] Data in the option buffer has been corrupted and cannot be read. 

[NSR_OPT_DATA_LEN] The supplied buffer is not large enough to receive the option. 

[NSR_OPT_ENTRY_NUM] The option index is negative or larger than the number of options in the opt 

buffer. 

AUTHOR 

readopt ( ) was developed by HP. 

SEE ALSO 

ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2), ipcerrmsg(3N), ipcgetnodename(2), ipclookup(2), 
ipcname(2), ipcnamerase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshut- 
down(2), addopt(3N), initopt(3N), optoverhead(3N), readopt(3N). 
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NAME 

regcmpO, regex() - compile and execute regular expression 

SYNOPSIS 

#include <stdlib.h> 

char * regcmp ( 

const char *stringl, 

/* string2 / */ . . . 

/*, (char *)0 */ 
} • 

char *regex(const char *re, const char *subject); 
extern char * loci; 

Remarks 

Features documented in this manual entry are obsolescent and may be removed in a future HP-UX release. 
Use of regcomp(3C) instead is recommended. 

DESCRIPTION 

regcmp ( ) compiles a regular expression and returns a pointer to the compiled form. malloc(3C) is used to 
create space for the vector. It is the user's responsibility to free unneeded space so allocated. A NULL 
return from regcmp ( ) indicates an incorrect argument. 

regex ( ) executes a compiled pattern against the subject string. Additional arguments are passed to 
receive values back, regex ( ) returns NULL on failure, or a pointer to the next unmatched character on 

success. A global character pointer loci points to where the match began. regcmp ( ) and 

regex () were largely borrowed from the editor, ed(l); however, the syntax and semantics have been 
changed slightly. The following are the valid symbols and their associated meanings: 

[ ] * . A These symbols retain their current meaning. 

$ Matches the end of the string; \n matches a new-line. 

Used within brackets the hyphen signifies a character range. For example, [ a- z ] is 
equivalent to [abed. . .xyz] . The - can represent itself only if used as the first or 
last character. For example, the character class expression [ } - ] matches the char- 
acters ] and -. 

+ A regular expression followed by + means one or more times. For example, [ - 9 ] + 

is equivalent to [0-9] [0-9]*. 

{m} {m, } {m,u} 

Integer values enclosed in { } indicate the number of times the preceding regular 
expression can be applied. The value m is the minimum number and u is a maximum 
number, which must be no greater than 256. The syntax {m} indicates the exact 
number of times the regular expression can be applied. The syntax {m, } is analo- 
gous to {m, infinity}. The plus (+)andasterisk (*) operations are equivalent to {1, } 
and { , } respectively. 

(...) $n The value of the enclosed regular expression is returned. The value is stored in the 

(»+l)th argument following the subject argument. A maximum often enclosed regu- 
lar expressions are allowed, regex ( ) makes its assignments unconditionally. 

(...) Parentheses are used for grouping. An operator, such as *, +, or { }, can work on a 

single character or a regular expression enclosed in parentheses. For example, 
(a*(cb+)*)$0. 

Since all of the above defined symbols are special characters, they must be escaped to be used as them- 
selves. 

regcmp ( ) and regex ( ) are kept in /lib/llbPW.a, and are linked by using the -lc and -1PW 
options to the Id or cc command. See WARNINGS below. 

EXAMPLES 

Match a leading new-fine in the subject string to which the cursor points. 
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char * curs or, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp(" A \n", 0)), cursor); 
free(ptr) ; 

Match through the string Testing3 and return the address of the character after the last matched char- 
acter (cursor+11). The string Testing3 will be copied to the character array ret 0. 

char ret0[9] ; 

char *newcursor, *name; 

name = regcmp( " ( [A-Za-z] [A-Za-z0-9_] {0,7} ) $0", 0); 
newcursor = regex(name, "123Testing321" / retO); 

WARNINGS 

regcmpO and regex() are kept in /lib/libPW.a. Unfortunately, /lib/libPW. a also contains 
some functions that have the same names as functions contained in the default C library, /lib/libc .a. 
To prevent unexpected results due to these name conflicts, always search libc before searching libPW. 
This is done with the Id (or cc) command line option sequence - lc - 1PW which satisifies all standard C 
functions from libc then searches libPW for the regcmp ( ) and regex ( ) functions (there is also an 
implied -lc following the explicit -1PW to satisfy any additional C functions required by regcmp () 
and regex ( ) ). 

User programs that use regcmp ( ) might run out of memory if regcmp ( ) is called iteratively without 
freeing vectors that are no longer required. 

SEE ALSO 

ed(l), malloc(3C), regcomp(3C). 



712 - 2 - HP-UX Release 9.0: August 1992 



regcomp(3C) regcomp(3C) 



NAME 

regcompO, regerror(), regexecQ, regfree() - regular expression matching routines 

SYNOPSIS 

ttinclude <regex.h> 

int regcomp(regex_t *preg, const char ♦pattern, int cflags); 

int regexec( 

const regex_t *preg, 

const char ♦string, 

size_t nmatch, 

regmatch_t pmatch [ ] , 

int eflags 
); 

void regfree(regex_t *preg); 

size_t regerror( 
int errcode, 
const regex_t *preg, 
char *errbuf, 
size_t errbuf_size 

); 

DESCRIPTION 

These functions interpret regular expressions as described in regexp(5). They support both basic and 
extended regular expressions. 

The structures regex_t and regmatch_t are defined in the header <regex .h>. 

The regex_t structure contains at least the following member (use of other members results in non- 
portable code): 

size_t re_nsub Number of parenthesized subexpressions. 

The regmat ch_t structure contains at least the following members: 

regoff_t rm_so Byte offset from start of string to start of substring. 

regofff_t rm_eo Byte offset from start of string to the first character after the end of the 

substring. 

regcomp ( ) compiles the regular expression specified by the pattern argument and places the results in 
the structure pointed to by preg. The cflags argument is the bit-wise logical OR of zero or more of the fol- 
lowing flags (defined in <regex . h>): 

REG_EXTENDED Use extended regular expressions. 

REG_NEWLINE IF REG_NEWLINE is not set in cflags, a newline character in pattern or string 
is treated as an ordinary character. If REG_NEWLINE is set, newlines are 
treated as ordinary characters except as follows: 

1. A newline in string is not matched by a period outside of a bracket 
expression or by any form of a nonmatching list. 

2. A circumflex ( A ) in pattern, when used to specify expression anchor- 
ing, matches the zero-length string immediately after a newline in 
string, regardless of the setting of REG_NOTBOL. 

3. A dollar-sign ($) in pattern, when used to specify expression anchor- 
ing, matches the zero-length string immediately before a newline in 
string, regardless of the setting of REG_NOTEOL. 

REG_ICASE 

Ignore case in match. If a character in pattern is defined in the current LC_CTYPE locale as having one or 
more opposite-case counterpoints, both the character and any counterpoints match the pattern character. 
This applies to all portions of the pattern, including a string of characters specified to be matched via a 
back-reference expression (\n). 
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Within bracket expressions: Collation ranges, character classes, and equivalence classes are effectively 
expanded into equivalent lists of collation elements and characters. Opposite-case counterpoints are then 
generated for each collation element or character to form the complete matching list or non-matching list 
for the bracket expression. Opposite-case counterpoints for a multi-character collating element include all 
possible combinations of opposite-case counterpoints for each individual character comprising the collating 
element. These are then combined to form new valid multi-character collating elements. For example, the 
opposite-case counterpoints for [ . ch . ] could be [ . Ch . ] , [ . cH . ] , and [ . CH . ] . 

REG_NOSUB 

Report only success/fail in regexec ( ) . 

The default regular expression type for pattern is Basic Regular Expression. The application can specify 
Extended Regular Expressions by using the REG_EXTENDED cflags value. 

If the function r egcomp ( ) succeeds, it returns zero; otherwise it returns a non-zero value indicating 
the error. 

If regcompO succeeds, and if the REG_NOSUB flag was not set in cflags, regcompO sets 
re_nsub to the number of parenthesized subexpressions (delimited by \ ( and \ ) in basic regular 
expressions or (and ) in extended regular expressions) found in pattern. 

regexec ( ) matches the null-terminated string specified by string against the compiled regular expres- 
sion preg initialized by a previous call to regcomp ( ) . If it finds a match, regexec ( ) returns zero; 
otherwise it returns non-zero indicating either no match or an error. The eflags argument is the bit-wise 
logical OR of the following flags: 

REG_NOTBOL The first character of the string pointed to by string is not the beginning of the 
line. Therefore, the circumflex character ( A ), when taken as a special character, 
never matches. 

REG_NOTEOL The last character of the string pointed to by string is not the end of the line. 
Therefore, the dollar sign ($), when taken as a special character, never 
matches. 

If nmatch is not zero, and REG_NOSUB was not set in the cflags argument to regcomp ( ) , then 
regexec ( ) fills in the pmatch array with byte offsets to the substrings of string that correspond to the 
parenthesized subexpressions of pattern: pmatch[i].rm_so is the byte offset of the beginning and 
pmatch[i].rm_eo is the byte offset one byte past the end of the substring i . (Subexpression i begins at the 
ith matched left parenthesis, counting from 1). Offsets in pmatch[0] identify the substring that 
corresponds to the entire regular expression. Unused elements of pmatch are set to -1. If there are more 
than nmatch subexpressions in pattern (pattern itself counts as a subexpression), regexec ( ) still does 
the match, but only records the first nmatch substrings. 

When matching a regular expression, any given parenthesized subexpression of pattern might partici- 
pate in the match of several different substrings of string, or it might not match any substring, even 
though the pattern as a whole did match. The following explains which substrings are reported in 
pmatch when matching regular expressions: 

1. If subexpression i in a regular expression is not contained within another subexpression, and 
it participated in the match several times, the byte offsets in pmatch[i] delimit the last such 
match. 

2. If subexpression i is not contained within another subexpression, and it did not participate in 
an otherwise successful match (because either *, ?, or I was used), then the byte offsets in 
pmatch[i] are-1. 

3. If subexpression i is contained in subexpression,/, and a match of subexpression j is reported 
yd. pmatch\j], the match or no-match reported in pmatch[i] is the last one that occurred within 
the substring in pmatchlj]. 

4. If subexpression i is contained in subexpression j, and the offsets in pmatchlj] are -1, the 
offsets in pmatch[i] will also be -1. 

5. If subexpression i matched a zero-length string, both offsets in pmatch[i] refer to the charac- 
ter immediately following the zero-length substring. 
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If REG_NOSUB was set in cflags in the call to regcomp ( ) , and nmatch is not zero in the call to 
regexec ( ) , the content of the pmatch array is unspecified. 

regf ree ( ) frees any memory allocated by regcomp ( ) associated with preg. 

If the preg argument to regexec ( ) or regf ree ( ) is not a compiled regular expression returned by 
regcomp ( ) , the result is undefined. A preg can no longer be treated as a compiled regular expression 
after it is given to regf ree () . 

regerror ( ) provides a mapping from error codes returned by regcomp ( ) and regexec ( ) to 
printable strings, regerror ( ) generates a string corresponding to the value of the errcode parame- 
ter, which was the last non-zero value returned by regcomp ( ) or regexec ( ) with the given value of 
preg. The errcode parameter can take on any of the error values defined in <regex . h>. It errbuf _size is 
not zero, regerror ( ) copies an appropriate error message into the buffer specified by errbuf. If the 
error message (including the terminating null) cannot fit in the buffer, it is truncated to errbuf _size - 1 
bytes and null terminated. 

If errbuf 'jsize is zero, the errbuf parameter is ignored, but the return value is as defined below. 

regerrorO returns the size of the buffer (including terminating null) that is required to hold the entire 
error message. 

EXTERNAL INFLUENCES 
Locale 

The LC_COLLATE category determines the collating sequence used in compiling and executing regular 
expressions. 

The LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, the 
characters matched by character-class expressions in regular expressions, and the opposite-case counter- 
part for each character. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

regcomp () returns zero for success and non-zero for an invalid expression or other failure, 
regexec ( ) returns zero if it finds a match and non-zero for no match or other failure. 

ERRORS 

If regcomp ( ) or regexec ( ) detects one of the error conditions listed below, it returns the correspond- 
ing non-zero error code. The error codes are defined in the header <regex . h>. 

REG_BADBR Contents of \ { \ } invalid: Not a number, number too large, more than two 

numbers, or first larger than second. 

REG_BADPAT Invalid regular expression. 

REG_BADRPT *, +, or + not preceded by valid regular expression. 

REG_EBRACE \ { \ } imbalance. 

REG_EBRACK [ ] imbalance. 

REG_ECOLLATE Invalid collation element referenced. 

REG_ECTYPE Invalid character class type named. 

REG_EDUPOPER Duplication operator in illegal position. 

REG_EESCAPE Trailing \ in pattern. 

REG_EMEM Out of memory while matching expression. 

REG_ENEWLINE new-line character found before end of pattern and REG_NEWLINE flag not set. 

REG_ENOEXPR No expression within ( ) or on one side of a I . 

REG_ENOSEARCH No remembered search string. 

REG_EPAREN \ ( \ ) imbalance in basic regular expression or ( ) imbalance in extended 

regular expression. 
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REG_ERANGE Invalid endpoint in range statement. 

REG_ESPACE Out of memory for compiled pattern. 

REG_ESUBREG Number in \digit invalid or in error. 

REG_NOMATCH regexec ( ) failed to match. 

REG_NSUB Too many parenthesis pairs or nesting level too deep. 

EXAMPLES 

/* match string against the extended regular expression in pattern, 
treating errors as no match. Return 1 for match, for no match. 
Print an error message if an error occurs. */ 

int 

match (string, pattern) 

char * string; 

char *pattern; 

{ 

int i; 

regex_t re; 

char buf [2 56] ; 

i=regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) ; 
if (i != 0) { 

(void) regerror (i,&re, buf ,sizeof buf) ; 

pr int f ( "%s \n " , buf ) ; 

return(O); /* report error */ 

} 

i = regexec (&re, string, (size_t) 0, NULL, 0); 
regf ree(&re) ; 
if (i != 0) { 

(void) regerror (i,&re, buf ,sizeof buf) ; 

printf ( "%b \n" , buf ) ; 

return(O); /* report error */ 

} 

return (1) ; 
} 

The following demonstrates how the REG_NOTBOL flag could be used with regexec ( ) to find all sub- 
strings in a line that match a pattern supplied by a user. 

(void) regcomp (&re, pattern, 0); 

/* look for first match at start of line */ 

error = regexec (&re, &buffer[0], 1, &pm, 0); 

while (error == 0) { /* while matches found */ 

/* find next match on line */ 

error = regexec (&re, fcbuff er [pm.rm_eo] , 1, &pm, REG_NOTBOL) ; 
} 

AUTHOR 

regcomp ( ) , regerror ( ) , regexec ( ) , and regf ree ( ) were developed by HP. 

SEE ALSO 

regexp(5). 

STANDARDS CONFORMANCE 

regcomp (): XPG4, POSK.2 
regerror ( ) : XPG4, POSIX.2 

regexec ( ) : XPG4, POSIX.2 
regf ree ( ) : XPG4, POSIX.2 
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NAME 

compileQ, step(), advanceQ - regular expression compile and match routines 

SYNOPSIS 

ftdefine INIT declarations 

#def ine GETC ( ) getc statements 

#def ine PEEKC ( ) peekc statements 

#define UNGETC(c) ungetc statements 

#def ine RETURN (pointer) return statements 

#def ine ERROR (val) error statements 

ttinclude <regexp.h> 

char *compile( 

const char *instring, 

char *expbuf, 

const char *endbuf, 

int eof 
); 

int step (const char *string, const char *expbuf); 

int advance (const char *string, const char *expbuf); 

extern char *locl, *loc2, *locs; 

extern int circf, sed, nbra; 

Remarks 

Features documented in this manual entry are obsolescent and may be removed in a future HP-UX release. 
Use of regcomp(SC) functions instead is recommended. 

DESCRIPTION 

These functions are general-purpose regular expression matching routines to be used in programs that per- 
form Basic Regular Expression (see regexp(5)) matching. These functions are defined in <regexp . h>. 

The functions step ( ) and advance ( ) do pattern matching given a character string and a compiled 
regular expression as input, compile ( ) takes a Basic Regular Expression as input and produces a com- 
piled expression that can be used with step() and advance () . 

The interface to this file is unpleasantly complex. Programs that include this file must have the following I 

five macros declared before the # include <regexp.h> statement. These macros are used by the * 

compile () routine. 

GETC ( ) Return the value of the next byte in the regular expression pattern. Successive calls to 

GETC ( ) should return successive bytes of the regular expression. 

PEEKC ( ) Return the next byte in the regular expression. Successive calls to PEEKC ( ) should 

return the same byte (which should also be the next byte returned by GETC ( ) . 

UNGETC (c ) Cause the argument c to be returned by the next call to GETC ( ) (and PEEKC ( ) ). No 
more than one byte of pushback is ever needed, and this byte is guaranteed to be the last 
byte read by GETC ( ) . The value of the macro UNGETC (c ) is always ignored. 

RETURN {pointer ) 

This macro is used on normal exit of the compile () routine. The value of the argument 
pointer is a pointer to the character after the last character of the compiled regular expres- 
sion. This is useful to programs that must manage memory allocation. 

ERROR {val ) This is the abnormal return from the compile ( ) routine. The argument val is an error 
number (see table below for meanings). This call should never return. 
Error Meaning 
11 Range endpoint too large. 

16 Bad number. 

25 "\digit" out of range . 

36 Illegal or missing delimiter. 
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41 No remembered search string. 

42 \ ( \ ) imbalance. 

43 Too many \ ( . 

44 More than 2 numbers given in \ { \ } . 

45 } expected after \. 

46 First number exceeds second in \ { \ } . 
48 [ ] imbalance. 

50 Regular expression overflow. 

The syntax of the compile ( ) routine is as follows: 

compile {instring , expbuf, endbuf, eofj 

The first parameter instring is never used explicitly by the compile ( ) routine, but is useful for pro- 
grams that pass down different pointers to input characters. It is sometimes used in the INIT declara- 
tion (see below). Programs that call functions to input characters or have characters in an external array 
can pass down a value of ( ( char * ) ) for this parameter. 

The next parameter expbuf is a character pointer. It points to the location where the compiled regular 
expression will be placed. 

The parameter endbuf is one more than the highest address where the compiled regular expression can 
be placed. If the compiled expression cannot fit in (endbuf -expbuf) bytes, a call to ERROR (50) is 
made. 

The parameter eof is the character which marks the end of the regular expression. For example, in ed(l), 
this character is usually a /. 

Each program that includes this file must have a #def ine statement for INIT. This definition is 
placed right after the declaration for the function compile () and the opening curly brace { . It is used 
for dependent declarations and initializations. Most often it is used to set a register variable to point to 
the beginning of the regular expression so that this register variable can be used in the declarations for 
GETC ( ) , PEEKC ( ) , and UNGETC ( ) . Otherwise it can be used to declare external variables that might 
be used by GETC ( ) , PEEKC ( ) , and UNGETC ( ) . See the example below of the declarations taken from 
grep(l). 

step ( ) also performs actual regular expression matching in this file. The call to step is as follows: 

step [string, expbuf J 

The first parameter to step ( ) is a pointer to a string of characters to be checked for a match. This 
string should be null-terminated. 

The second parameter expbuf is the compiled regular expression that was obtained by a call to com- 
Pile(). 

step ( ) returns non-zero if the given string matches the regular expression, and zero if the expressions 
do not match. If there is a match, two external character pointers are set as a side effect to the call to 
step ( ) . The variable set in step ( ) is loci. This is a pointer to the first character that matched the 
regular expression. The variable loc2, which is set by the function advance ( ) , points to the charac- 
ter after the last character that matches the regular expression. Thus, if the regular expression matches 
the entire line, loci points to the first character of string and loc2 points to the null at the end of 
string. 

step() uses the external variable circf (), which is set by compile () if the regular expression 
begins with A . If this is set, step ( ) tries to match the regular expression to the beginning of the string 
only. If more than one regular expression is to be compiled before the first is executed, the value of circf 
should be saved for each compiled expression and circf should be set to that saved value before each call 
to step(). 

advance ( ) is called from step ( ) with the same arguments as step ( ) . The purpose of step ( ) is 
to step through the string argument and call advance ( ) until advance ( ) returns non-zero, which 
indicates a match, or until the end of string is reached. To constrain string to beginning-of-line in all 
cases, step ( ) need not be called; simply call advance ( ) . 

When advance ( ) encounters a * or \ { \ } sequence in the regular expression, it advances its pointer 
to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the 
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string to the rest of the regular expression. As long as there is no match, advance backs up along the 
string until it finds a match or reaches the point in the string that initially matched the * or \ { \ } . It 
is sometimes desirable to stop this backing up before the initial point in the string is reached. If the 
external character pointer Iocs is equal to the point in the string at sometime during the backing up 
process, advance ( ) breaks out of the loop that backs up and returns zero. This is used by ed(l) and 
sed(l) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, 
expressions such as s /y* / /g do not loop forever. 

The additional external variables sed and nbra are used for special purposes. 

EXTERNAL INFLUENCES 
Locale 

The LC_COLLATE category determines the collating sequence used in compiling and executing regular 
expressions. 

The LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and 
the characters matched by character class expressions in regular expressions. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

EXAMPLES 

The following is an example of how the regular expression macros and calls look fromgrep(l): 

ttdefine INIT register char *sp = instring; 

ttdefine GETCO (*sp+ + ) 

ttdefine PEEKCO (*sp) 

ttdefine UNGETC(c) (--sp) 

ttdefine RETURN (c) return; 

ttdefine ERROR (c) regerrO 

ttinclude < regexp. h> 

(void) compile (*argv, expbuf, &expbuf [ESIZE] , '\0'); 

if (step(linebuf , expbuf)) 
succeed () ; 

SEE ALSO ■ 

grep(l), regcomp(3C), setlocale(3C), regexp(5). | 

STANDARDS CONFORMANCE 

advance ( ) : AES, SVID2, XPG2, XPG3, XPG4 
compile ( ) : AES, SVID2, XPG2, XPG3, XPG4 

loci: AES, SVID2, XPG2, XPG3, XPG4 
loc2: AES, SVID2, XPG2, XPG3, XPG4 

Iocs: AES, SVID2, XPG2, XPG3, XPG4 
step ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

reltimer - relatively arm a per-process timer 

SYNOPSIS 

#lnclude <sys/timers.h> 

int reltimer ( 

timer t timericl/ 

struct itimerspec *value, 

struct itimerspec *ovalue, 
); 

DESCRIPTION 

reltimer ( ) sets the it_value of the specified timer to an offset from the current clock setting. 

If reltimer ( ) specifies a value argument with the it_value member equal to zero, the timer is dis- 
abled, reltimer () updates the itjnterval value of the timer to the value specified. Time values 
smaller than the resolution of the specified timer are rounded up to its resolution; timer values larger than 
the maximum value of the specified timer are rounded down to the maximum value (see mktimer(3C)). 

reltimer ( ) returns in the ovalue parameter a value representing the previous amount of time before the 
timer would have expired or zero if the timer was disabled, together with the previous interval timer period. 
The members of ovalue are subject to the resolution of the timer, and are the same values that would be 
returned by a gettimerO call. 

The behavior of this function is undefined if value is NULL. 

RETURN VALUE 

Upon successful completion, reltimer ( ) returns zero; otherwise, it returns -1 and sets errno to indi- 
cate the error. 

ERRORS 

reltimerQ fails if any of the following conditions are encountered: 

[EINVAL] timerid does not correspond to an ID returned by mktimer ( ) or the value structure 

specified a nanosecond value less than zero or greater than or equal to 1000 million. 

[EIO] An error occurred while accessing the clock device. 

SEE ALSO 

gettimer(3C), mktimer(3C), <sys/timers.h>. 

STANDARDS CONFORMANCE 

reltimer():AES 
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NAME 

removeQ - remove a file 

SYNOPSIS 

ttinclude <stdio.h> 

int remove (const char *path) ; 

DESCRIPTION 

remove () removes the file named by path. If path does not name a directory, remove {path) is 
equivalent to unlink {path ) . If path names a directory, remove {path ) is equivalent to rmdir {path ) . 

SEE ALSO 

rmdir(2), unlink(2). 

STANDARDS CONFORMANCE 

remove ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

res_query(), res_search(), res_mkquery(), res_send(), res_init(), dn_comp(), dn_expand(), herror() - 
resolver routines 

SYNOPSIS 

#include <sys/types.h> 
#include <netinet/in.h> 
#inciude <arpa /names er .h> 
#include <resolv.h> 

int res_query( 

char *dname, 

int class, 

int type, 

u_char *answer, 

int anslen 
); 

int res_search ( 

char *dname, 

int class, 

int type, 

u_char *answer, 

int anslen 
); 

int res_mkquery( 

int op, 

char *dname, 

int class, 

int type, 

char *data, 

int datalen, 

struct rrec *newrr, 

char *buf, 

int buflen 
); 

int res_send(char *msg, int msglen, char *answer, int anslen); 

void res_init ( ) ; 

int dn_comp( 

char *exp_dn, 

char *comp_dn, 

int length, 

char **dnptrs, 

char **lastdnptr 
); 

int dn_expand ( 

char *msg, 

char *eomorig, 

char *comp_dn, 

char exp_dn, 

int length 
' ); 

extern int h_errno; 

void herror(char *s); 

DESCRIPTION 

These routines are used for making, sending and interpreting query and reply messages with Internet 
domain name servers. 
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Global configuration and state information used by the resolver routines is kept in the structure _res. 
Most of the values have reasonable defaults and can be ignored. Options stored in _res .options are 
defined in <resolv . h> and are as follows. Options are stored as a simple bit mask containing the bitwise 
OR of the options enabled. 

True if the initial name server address and default domain name are initialized 
(i.e., res_init ( ) has been called). 

Print debugging messages. 

Accept authoritative answers only. With this option, res_send ( ) should con- 
tinue until it finds an authoritative answer or finds an error. Currently this is 
not implemented. 

Query the primary server only. Currently this is not implemented. 

Use TCP connections for queries instead of UDP datagrams. 

Used with RES_USEVC to keep the TCP connection open between queries. This 
is useful only in programs that regularly do many queries. UDP should be the 
normal mode used. 

The name server will set the truncation bit if all of the data does not fit into the 
response datagram packet. If RES_IGNTC is set, res_send() will not retry 
the query with TCP (i.e., ignore truncation errors). 

Set the recursion-desired bit in queries. This is the default. (res_send() 
does not do iterative queries and expects the name server to handle recursion.) 

If set, res_search ( ) appends the default domain name to single-component 
names (those that do not contain a dot). This option is enabled by default. 

If this option is set, res_search( ) searches for host names in the current 
domain and in parent domains; see hostname(5). This is used by the standard 
host lookup routine gethostbyname ( ) (see gethostbynameiSN)). This 
option is enabled by default. 



RES_INIT 

RES_DEBUG 
RES_AAONLY 

RES_PRIMARY 

RES_USEVC 

RES_STAYOPEN 

RES_IGNTC 

RES_RECURSE 
RES_DEFNAMES 
RES DNSRCH 



Primary Routines 

res_init () 



res_query( ) 



res_search() 



Reads the configuration file, /etc/resolv . conf , to get the default domain name, 
search fist, and the Internet address of the local name server(s). If no server is 
configured, the host running the resolver is tried. The current domain name is 
defined by the hostname if not specified in the configuration file; it can be overridden 
by the environment variable LOCALDOMAIN. Initialization normally occurs on the 
first call to one of the following routines. If there are errors in the configuration file, 
they are silently ignored. 

Provides an interface to the server query mechanism. It constructs a query, sends it 
to the local server, awaits a response, and makes preliminary checks on the reply. 
The query requests information of the specified type and class for the specified fully- 
qualified domain name dname . The reply message is left in the answer buffer with 
length anslen supplied by the caller. 

Makes a query and awaits a response much like res_query ( ) , but in addition, it 
implements the default and search rules controlled by the RES_DEFNAMES and 
RES_DNSRCH options. It returns the first successful reply. 



Other Routines 

Routines described here are lower-level routines used by res_query ( ) . 



res_mkquery ( ) 



Constructs a standard query message and places it in buf. It returns the size of the 
query, or -1 if the query is larger than buflen. The query type op is usually QUERY, 
but can be any of the query types denned in <arpa/nameser .h>. The domain 
name for the query is given by dname. class can be any of the query classes defined in 
<arpa/nameser.h>. type can be any of the query types defined in 
<arpa/nameser.h>. data is the data for an inverse query (IQUERY). newrr is 
currently unused but is intended for making update messages. 
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res_send() Sends a pre-formatted query and returns an answer. It calls res_init() if 

RES__INIT is not set, sends the query to the local name server, and handles timeouts 
and retries. res_send( ) returns the length of the reply message, or -1 if there 
were errors. 

dn_comp() Compresses the domain name exp_dn and stores it in compjdn. The size of the 

compressed name is returned or -1 if there were errors, length is the size of the array 
pointed to by comp_dn. The compression uses an array of pointers dnptrs to previ- 
ously compressed names in the current message. The first pointer points to to the 
beginning of the message and the list ends with NULL. The limit to the array is 
specified by lastdnptr. A side effect of dn_comp( ) is to update the fist of pointers 
for labels inserted into the message as the name is compressed. If dnptr is NULL, 
names are not compressed. If lastdnptr is NULL, the list of labels is not updated. 

dn_expand ( ) Expands the compressed domain name compjdn to a full domain name. The 

compressed name is contained in a query or reply message; msg is a pointer to the 
beginning of the message. The uncompressed name is placed in the buffer indicated 
by expjin which is of size length. The size of compressed name is returned or -1 if 
there was an error. 

RETURN VALUE 

Error return status from res_search() is indicated by a return value of -1. The external integer 
h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. 
The routine herror ( ) can be used to print an error message describing the failure. The argument string 
s is printed first, followed by a colon, a blank, the message, and a new-line. 

ERRORS 

h_er rno can have the following values: 

HOST_NOT_FOUND No such host is known. 

TRY_AGAIN This is usually a temporary error and means that the local server did not receive 

a response from an authoritative server. A retry at some later time may 
succeed. 

NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable 

error. 



NO DATA 



The name is known to the name server, but there is no data of the requested 
type associated with this name; this is not a temporary error. Another type of 
request to the name server using this domain name will result in an answer. 



AUTHOR 

These resolver routines were developed by the University of California, Berkeley. 

FILES 

/et c /resolv . conf resolver configuration file 

SEE ALSO 

named(lm), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035. 
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NAME 

rexec() - return stream to a remote command 

SYNOPSIS 

int rexec ( 

char **ahost, 
int inport , 
const char *user, 
const char *passwd, 
const char *cmd, 
int *f d2p) ; 

DESCRIPTION 

rexec ( ) arranges for the remote execution oicmd on the host *ahost as user, who is authenticated with 
passwd. It returns a file descriptor for the socket to which the standard input and standard output ofcmd 
are attached. A command-level interface to rexec ( ) is provided by the rexec command (see remsh{Vj). 

rexec ( ) looks up host *ahost using gethostbyname ( ) (see gethostbyname (3N)) and returns -1 if the 
host does not exist. The host name can be either the official name or an alias. If the gethostbyname ( ) 
call succeeds, *ahost is set to the standard name of the host, rexec ( ) passes a username and password 
to the remote host for authentication. These can be specified in the user and passwd parameters to 
rexec ( ) . If either is NULL, rexec ( ) searches for the appropriate information in the . net re file (see 
netrc(4)) in the users's home directory. If this fails, rexec ( ) prompts the user for the remote user name 
and password, defaulting to the local user name and a NULL password. 

inport specifies which TCP port to use for the connection; it is normally the value returned by 
get servbyname(" exec", "tcp") (see getservent(3N)). The protocol used by rexec ( ) is described 
in detail in rexecd (1M). 

If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the remote com- 
mand as st din and stdout . If the connection to the socket is refused after five tries, or if it was refused 
for a reason other than the port being in use, rexec ( ) returns -1. \ifd2p is non-zero, an auxiliary con- 
nection to a control process is set up and a file descriptor for it is placed in *fd2p. The control process 
returns diagnostic output from the command on this connection and accepts bytes on this connection, inter- 
preting them as UNIX signal numbers to be forwarded to the process group of the command. If the auxiliary 
port cannot be set up, rexec ( ) returns -1. \ifd2p is 0, stderr of the remote command is made the 
same as stdout and no provision is made for sending arbitrary signals to the remote process. 

DIAGNOSTICS 

rexec ( ) produces the following diagnostic messages: 

hostname : Unknown host 

The remote host name was not found by gethostbyname ( ) . 

system call:... 

Error in executing the system call. A message specifying the cause of the failure is appended to this 
message. 

connect : hostname : . . . 

Error in connecting to the socket obtained for rexec ( ) . A message specifying the cause of the 
failure is appended to this diagnostic. 

Secondary socket : . . . 

Error in creating a secondary socket for error transmission to be used by rexec ( ) . 

read : hostname : . . . 

Error in reading information transmitted over the socket. A message specifying the cause of the 
failure is appended to this diagnostic. 

Connection timeout 

The remote host did not connect within 30 seconds to the secondary socket set up as an error connec- 
tion. 

Lost connection 

The program attempts to read from the socket and fails. This means the socket connection with the 
remote host was lost. 

HP-UX Release 9.0: August 1992 - 1 - 725 



I 



I 



rexec(3N) rexec(3N) 



.net re: . . . 

Error in opening . net re file in the home directory for a reason other than the file not existing. 

Error- .netrc file not correct mode. 
Remove password or correct mode. 

The . netrc file is readable, writable or executable by anyone other than the user. 

Next step: Check whether .netrc has been modified by someone else and change the mode of 
. net re (chmod 400 .netrc). 

Unknown .netrc option . . . 

An unrecognized keyword has been found in . netrc (see netrc(4)). 

Next step : Correct keyword in . ne t r c . 

primary connection shutdown 

While waiting for the secondary socket to be set up, rexec ( ) had its primary connection shut down. 
This may have been caused by the inetd security failure. 

recv. ... 

While trying to set up the secondary (stderr) socket, rexec ( ) had an error condition on its pri- 
mary connection. 

accept: Interrupted system call 

While trying to set up a secondary socket, rexec ( ) ran out of a resource, which caused the accept to 
be timed out. 

Next step: Repeat the command. If a timeout occurs, check whether the ARPA Services are installed 
and inetd is running. 

EXAMPLE 

To execute the date command on remote host hpxzgy using the remote account chm, rexec () could 
be used as follows: 

# include <sys/types.h> 

#include < sys/ socket .h> 

#include <sys/ioctl.h> 

#include <netinet/in.h> 

#include <netdb.h> 

#include <stdio.h> 

char *host[] = { "hpxzgy" }; 

char *user = "chm"; 

char *passwd = "password"; 

char *cmd = "date"; 

main(argc, argv) 
char **argv; 
int argc ; 



{ 



char ch; 

struct servent *servent; 

FILE *fp; 

int sd; 

servent = getservbyname("exec" , "tcp" ); 

sd = rexec (host, servent->s_port, user, passwd, cmd, 0); 
fp = fdopen(sd, "r"); 
while ((ch = getc(fp)) != EOF) 
put char (ch) ; 



} 



WARNINGS 

There is no way to specify options to the socket ( ) call that rexec ( ) makes. 
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A program using rexec ( ) should not be put in the background when rexec ( ) is expected to prompt for 
a password or user name. If it is put in the background it will compete with the shell for input. 

Since rexec ( ) replaces the pointer to the hostname (*ahost) with a pointer to the standard name of the 
host in a static data area, this value must be copied into the user's data area if it is to be used later. 

The password is sent unencrypted through the socket connection. 

AUTHOR 

rexec ( ) was developed by the University of California, Berkeley. 

SEE ALSO 

remsh(l), rexecd(lM), gethostent(3N), getservent(3N), rcmd(3N), netrc(4). 
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NAME 

rmtimer - free a per-process timer 

SYNOPSIS 

#include <sys/ timers .h> 

int rmtimer (timer_t timerid) ; 

DESCRIPTION 

rmtimer ( ) is used to free a previously allocated timer (returned by mktimer ( ) . Any pending timer 
event to be generated by this timer has been cancelled when the call returns. 

RETURN VALUE 

Upon successful completion, rmtimer ( ) returns zero; otherwise, it returns -1 and sets errno to indi- 
cate the i 



ERRORS 

rmtimerQ fails if the following condition is encountered: 

[EINVAL] timerid is not a valid timer ID. 

SEE ALSO 

mktimer(3C), reltimer(3C), <sys/timers.h> 

STANDARDS CONFORMANCE 

rmtimer():AES 
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NAME 

rnusersO, rusers() - return information about users on remote machines 

SYNOPSIS 

#include <utmp.h> 
ttinclude <rpcsvc/rusers.h> 

int rnusers(char *host) ; 

int rusers(char *host, struct utmpidlearr *up); 

DESCRIPTION 

rnusers ( ) returns the number of users logged in on host or -1 if it cannot determine that number. 
The host string is either the official name of the host or an alias for it. See hosts(4) for more 
information regarding host names. 

rusers ( ) fills in the utmpidlearr structure with data about host and returns if successful. The 
ut_l ine field is limited to eight characters on Berkeley systems, so the HP-UX XDR rou- 
tine truncates from 12 characters to 8. The nonuser ( ) macro does not exist in the HP- 
UX utmp . h file; therefore, HP-UX windows appear as separate users. 

The relevant structures are: 

struct utmparr { /* RUSERSVERS_ORIG */ 

struct utmp **uta_arr; 

int uta_cnt; 
}; 

struct utmpidle { 

struct utmp ui_utmp; 

unsigned ui_idle; 
}; 

struct utmpidlearr { /* RUSERSVERS_IDLE */ 

struct utmpidle **uia_arr; 

int uia_cnt; 
}; 

RPC Information ■ 

program number: | 

RUSERSPROG 

xdr routines: 

int xdr_utmp(xdrs, up) 

XDR *xdrs; 

struct utmp *up; 
int xdr_utmpidle(xdrs, ui) 

XDR *xdrs; 

struct utmpidle *ui; 
int xdr_utmpptr(xdrs, up) 

XDR*xdrs; 

struct utmp **up; 
int xdr_utmpidleptr(xdrs, up) 

XDR *xdrs; 

struct utmpidle **up; 
int xdr_utmparr(xdrs, up) 

XDR *xdrs; 

struct utmparr *up; 
int xdr_utmpidlearr(xdrs, up) 

XDR *xdrs; 

struct utmpidlearr *up; 

procs: 

RUSERSPROC_NUM 
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No arguments, returns number of users as an 

unsigned long. 
RUSERSPROC.NAMES 

No arguments, returns utmparr or utmpidlearr, 

depending on version number. 
RUSERSPROC.ALLNAMES 

No arguments, returns utmparr or utmpidlearr, 

depending on version number. Returns listing even 

for utmp entries satisfying nonuserQ in utmp.h. 

versions: 

RUSERSVERS.ORIG 
RUSERSVERSJDLE 

structures: 

WARNING 

User applications that call this routine must be linked with /usr/include/librpcsvc . a. For exam- 
ple, 

cc my_source.c -lrpcsvc 

AUTHOR 

rnusers ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

rusers(l). 
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NAME 

rpc() - library routines for remote procedure calls 

DESCRIPTION 

These routines allow C programs to make procedure calls on other machines across the network. First, the 
client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a 
dispatch routine to perform the requested service and then sends back a reply. Finally, the procedure call 
returns to the client. 



Functions 

auth_deatroy ( ) 

authnone_create ( ) 
authunix_create ( ) 



Destroy authentication information handle. 
Return RPC authentication handle with no checking. 
Return RPC authentication handle with UNIX permissions. 



authunix_create_def ault ( ) 

Return default UNIX authentication handle. 



callrpc( ) 
clnt_broadcast ( ) 
clnt-call ( ) 
clnt_control ( ) 
clnt_create() 
clnt_destroy ( ) 
clnt_f reeres ( ) 
clnt_geterr() 
clnt_pcreateerror ( ) 
clnt_perrno ( ) 
clnt_perror ( ) 
clnt_spcreateerror ( ) 

clnt_sperrno ( ) 

clnt_sperror ( ) 
clntraw_create ( ) 
clnttcp_create ( ) 
clntudp_create ( ) 
get_myaddress ( ) 
gettransient ( ) 
pmap_getmaps ( ) 
pmap_getport ( ) 
pmap_rmtcall ( ) 
pmap_set () 
pmap_unset () 
registerrpc( ) 
rpc_createerr ( ) 
svc_des troy- 



Call remote procedure, given [prognum,versnum,procnum]. 

Broadcast remote procedure call everywhere . 

Call remote procedure associated with client handle. 

Change or retrieve information associated with a client handle. 

Create RPC client using the transport specified by the caller. 

Destroy client's RPC handle. 

Free data allocated by RPC/XDR system when decoding results. 

Copy error information from client handle to error structure. 

Print message to stderr about why client handle creation failed. 

Print message to stderr corresponding to condition given. 

Print message to stderr explaining why an RPC call failed. 

Return a pointer to a null-delimited string telling why the client handle 
creation failed. 

Return a pointer to a null-dehmited string containing a message 
corresponding to the error value passed to this function. 

Return a pointer to a null-delimited string telling why an RPC call failed. 

Create toy RPC client for simulation. 

Create RPC client using TCP transport. 

Create RPC client using UDP transport. 

Get the machine's IP address. 

Get a program number in the transient range. 

Return list of RPC program-to-port mappings. 

Return port number on which waits supporting service. 

Instruct portmapper to make an RPC call. 

Establish mapping between [prognum,versnum,procnum] and port. 

Destroy mapping between [prognum,versnum,procnum] and port. 

Register procedure with RPC service package. 

Global variable indicating reason why client creation failed. 

Destroy RPC service transport handle. 
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svc_f dset ( ) 

svc_f reeargs ( ) 
svc_getargs ( ) 
svc_getcaiier ( ) 
svc_getreqset ( ) 
svc_register ( ) 
svc_run ( ) 
svc_sendrepiy ( ) 
svc_unregister ( ) 
svcerr_auth( ) 
svcerr_decode ( ) 
svcerr_noproc ( ) 
svcerr_noprog ( ) 
svcerr_progvers ( ) 
svcerr_systemerr ( ) 
svcerr_weakauth( ) 
svcf d_create ( ) 
svcraw_create ( ) 
svctcp_create ( ) 
svcudp_create ( ) 
xdr_accepted_reply ( ) 
xdr_authunix_parms ( ) 
xdr_callhdr() 
xdr_callmsg( ) 
xdr_opaque_auth ( ) 
xdr_pmap ( ) 
xdr pmap 1 i s t ( ) 
xdr_re jected_reply ( ) 
xdr_replymsg ( ) 
xprt_register ( ) 
xprt_unregister ( ) 



Global array with RPC service file descriptor mask; can handle up to 
NOFILE socket descriptors (NOFILE defined in header file 
<sys/parm.h>). 

Free data allocated by RPC/XDR system when decoding arguments. 

Decode the arguments of an RPC request. 

Get the network address of the caller of a procedure. 

Return when all associated sockets have been serviced. 

Associate prognum and versnum with service dispatch procedure. 

Wait for RPC requests to arrive and call appropriate service. 

Send back results of a remote procedure call. 

Remove mapping of [prognum, versnum] to dispatch routines. 

Called when refusing service because of authentication error. 

Called when service cannot decode its parameters. 

Called when service hasn't implemented the desired procedure. 

Called when program is not registered with RPC package. 

Called when version is not registered with RPC package. 

Called when service detects system error. 

Called when refusing service because of insufficient authentication. 

Create an RPC service from an existing socket. 

Create a toy RPC service transport for testing. 

Create an RPC service based on TCP transport. 

Create an RPC service based on UDP transport. 

Generate RPC-style replies without using RPC package. 

Generate UNIX credentials without using RPC package. 

Generate RPC-style headers without using RPC package. 

Generate RPC-style messages without using RPC package. 

Describe RPC messages, externally. 

Describe parameters for portmap procedures, externally. 

Describe a list of port mappings, externally. 

Generate RPC-style rejections without using RPC package. 

Generate RPC-style replies without using RPC package. 

Register RPC service transport with RPC package. 

Unregister RPC service transport from RPC package 



AUTHOR 

rpc was developed by Sun Microsystems, Inc. 

SEE ALSO 

Programming and Protocols for NFS Services . 
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NAME 

rstat(), havedisk() - get performance data from remote kernel 

SYNOPSIS 

ttinclude <time.h> 
#include <rpcsvc/rstat .h> 

int havedisk(char *host) ; 

int rstat(char *host, struct statstime *statp) ; 

DESCRIPTION 

havedisk( ) returns 1 if host has a disk, if it does not, and -1 if this cannot be determined. The host 
string is either the official name of the host or an alias for it. See hosts(4) for more information regarding 
host names. 

rstat ( ) fills in the statstime structure for host, and returns if it was successful. The relevant struc- 
tures are: 



struct stats { 

int cp_time[CPUSTATES] ; 
int dk_xf e r [ DK_NDR I VE ] ; 

unsigned v_pgpgin; 
unsigned v_pgpgout; 
unsigned v_pswpin; 
unsigned v_pswpout; 
unsigned v_intr; 
int if_lpackets; 
int if_ierrors; 
int if_opackets; 
int if_oerrors; 
int if_collisions; 
}/ 



/* RSTATVERS_ORIG */ 

/* the time spent in each CPU state */ 

/* total number of disk transfers 

on each of the disk interfaces */ 
/* total YM pages paged in */ 
/* total VM pages paged out */ 
/* total VM pages paged swapped in */ 
/* total VM pages paged swapped out */ 
/* total interrupts */ 

/* inbound packets on all interfaces */ 
/* Inbound errors on all interfaces */ 
/* outbound packets on all interfaces */ 
/* outbound errors on all interfaces */ 
/*. collisions seen on all interfaces */ 



struct statsswtch { 

int cp_time[CPUSTATES] ; 
int dk_xf e r [ DK_NDR IVE ] ; 

unsigned v_pgpgin; 
unsigned v_pgpgout; 
unsigned vjpswpin; 
unsigned v_pswpout; 
unsigned v_intr; 
int if_ipackets; 
int if_ierrors; 
int if_opackets; 
int if_oerrors; 
int if_collisions; 
unsigned v_swtch; 
long avenrun [3 ] ; 
struct timeval boottime; 
}; 



/* RSTATVERS_SWTCH */ 

/* the time spent in each CPU state */ 

/* total number of disk transfers 

on each of the disk interfaces */ 
/* total VM pages paged in */ 
/* total VM pages paged out */ 
/* total VM pages paged swapped in */ 
/* total VM pages paged swapped out */ 
/* total interrupts */ 

/* inbound packets on all interfaces */ 
/* inbound errors on all interfaces */ 
/* outbound packets on all interfaces */ 
/* outbound errors on all interfaces */ 
/* collisions seen on all interfaces */ 
/* total context switches */ 
/* average number of running jobs */ 
/* time of last boot */ 



struct statstime { 

int cp_t ime [ CPUSTATE S ] ; 
int dk_xf e r [ DK_NDR IVE ] ; 

unsigned v_pgpgin; 
unsigned v_pgpgout; 
unsigned v_pswpin; 
unsigned v_pswpout; 



/* RSTATVERS_TIME */ 

/* the time spent in each CPU state */ 

/* total number of disk transfers 

on each of the disk interfaces */ 

/* total VM pages paged in */ 

/* total VM pages paged out */ 

/* total VM pages paged swapped in */ 

/* total VM pages paged swapped out .*/ 
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unsigned v_intr; /* 

int if_ipackets; /* 

int if_ierrors; /* 

int if_opackets; /* 

int if_oerrors; /* 

int if_collisions; /* 

uilS xy Hsu V SWtCii| /" 

1 ong avenrun [ 3 ] ; / * 

struct timeval boot time; /* 

struct timeval curtime; /* 



total interrupts */ 

inbound packets on all interfaces */ 
inbound errors on all interfaces */ 
outbound packets on all interfaces */ 



}; 



outbound errors on all interfaces 
collisions seen on all interfaces 
total context switches */ 
average number of running jobs */ 
time of last boot */ 
current system time */ 



RPC Info 

program number: 

RSTATPROG 

xdr routines: 

int xdr_stats(xdrs, stat) 

XDR *xdrs; 

struct stats *stat; 
int xdr_statsswtch(xdrs, stat) 

XDR *xdrs; 

struct statsswtch *stat; 
hit xdr_statstime(xdrs, stat) 

XDR *xdrs; 

struct statstime *stat; 
int xdr_timeval(xdrs, tv) 

XDR *xdrs; 

struct timeval *tv; 

procs: 

RSTATPROC.HAVEDISK 

Takes no arguments, returns long 

which is true if remote host has a disk. 
RSTATPROC.STATS 

Takes no arguments, return struct statsxxx, 

depending on version, 
versions: 

RSTATVERS.ORIG 

RSTATVERS.SWTCH 

RSTATVERSJTIME 

WARNING 

User applications that call this routine must be linked with /usr/include/librpcsvc . a. For exam- 
ple, 

cc my_source.c -lrpcsvc 

AUTHOR 

rs tat ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

rup(l), rstatd(lM). 
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NAME 

rwall() - write to specified remote machines 

SYNOPSIS 

#include <rpcsvc/rwall .h> 

int rwall(char *host, char *msg) ; 

DESCRIPTION 

rwal 1 ( ) causes host to print the string msg to all its users. It returns if successful. 

RPC Info 

program number: 
WALLPROG 

procs: 

WALLPROCJWALL 

Takes string as argument (wrapstring), returns no 
arguments. Executes wall on remote host with 
string, 
versions: 

RSTATVERS_ORIG 

WARNING 

User applications that call this routine must be linked with /usr/include/librpcsvc . a. For exam- 
ple, 

cc my_source.c -lrpcsvc 

AUTHOR 

rwall ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

rwall(lM), rwalld(lM), shutdown(lM). 
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NAME 

scandir(), alphasort() - scan a directory 

SYNOPSIS 

#include <dirent.h> 

int scandir( 

const char *dirname / 

struct dirent **namelist / 

int (*select) (const struct dirent * const *), 

int (* compar) ( 

const struct dirent * const *, 

const struct dirent * const * 
) 

);' 

int alphasort ( 

const struct dirent * const *dl, 

const struct dirent * const *d2 
); 

DESCRIPTION 

scandir ( ) reads the directory dirname and builds an array of pointers to directory entries using mal- 
loc ( ) (see malloc(3C)). It returns the number of entries in the array and a pointer to the array through 
namelist. 

The select parameter is a pointer to a user-supplied subroutine which is called by scandir ( ) to select 
which entries are to be included in the array. The select routine is passed a pointer to a directory entry and 
should return a non-zero value if the directory entry is to be included in the array. If select is null, then all 
the directory entries will be included. 

The compar parameter is a pointer to a user-supplied subroutine which is passed to qsort(3C) to sort the 
completed array. If this pointer is null, the array is not sorted, alphasort ( ) is a routine which can be 
used for the compar parameter to sort the array alphabetically. 

The memory allocated for the array can be deallocated with free() (see mallociZC)) by freeing each 
pointer in the array and the array itself. 

EXTERNAL INFLUENCES 
Locale 

The LC_COLLATE category determines the collation ordering used by alphasort ( ) . See hpnls(5) for a 
description of supported collation features. 

The LC_CTYPE category determines the interpretation of bytes in the file name portion of directory 
entries as single- and/or multi-byte characters by the alphasort ( ) function. 

Results are undefined if the locales specified by the LC_COLLATE and LC_CTYPE categories use 
different code sets. 

International Code Set Support 

Single- and multi-byte character code sets are supported for alphasort ( ) . 

RETURN VALUE 

scandir () returns -1 if the directory cannot be opened for reading or if malloc() cannot allocate 
enough memory to hold all the data structures. 

EXAMPLE 

The example program below scans the /tmp directory. It does not exclude any entries since select is NULL. 
The contents of namelist are sorted by alphasort ( ) . It prints out how many entries are in /tmp 
and the sorted entries of the /tmp directory. The memory used by scandir () is returned using 
free(). 

# include <sys/types.h> 
#include <stdio.h> 
#include <dirent.h> 
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extern int scandir(); 
extern int alphasort ( ) ; 

main( ) 
{ 

int num_entries, i; 

struct dirent **namelist, **list; 

if ( (num_entries = scandir ("/tmp", &namelist, NULL, alphasort)) < 0) { 
f print f (stderr, "Unexpected error\n"); 
exit(l); 
} 

printf ( "Number of entries is %d\n", num_entries) ; 
if (num_entries) { 

printf ("Entries are:"); 

for (i=0, list=namelist; i<num_entries; i++) { 
printf (" %a" , (*list)->d_name) ; 
free(*list); 
*list++; 
} 

free(namelist) ; 
printf ("\n") ; 
} 

printf ("Xn") ; 
exit ( ) ; 
} 

SEE ALSO 

directory(3C), malloc(3C), qsort(3C), string(3C), dirent(5), hpnls(5). 
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NAME 

scanf, fscanf, sscanf, nl_scanf, nljfscanf, nl_sscanf - formatted input conversion, read from stream file 

SYNOPSIS 

#include <stdio.h> 

int scanf (const char *format, /* [pointer,] */ ...); 

int fscanf (FILE *stream, const char *format / /* [pointer,] */ ...); 

int sscanf (const char *s, const char *format, /* [pointer,] */ ...); 

int nl_scanf (const char *format, /* [pointer,] */ ...); 

int nl_f scanf (FILE *stream, const char *format, /* [pointer,] */ ...); 

int ni_s scanf (const char *s, const char *format, /* [pointer,] */ ...); 

DESCRIPTION 

scanf ( ) and nl_scanf ( ) read from the standard input stream stdin. 

fscanf () and nl_f scanf () read from the named input stream. 

sscanf () and nl_sscanf () read from the character strings. 

Each function reads characters, interprets them according to the control string format argument, and stores 
the results in its pointer arguments. If there are insufficient arguments for the format, the behavior is 
undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The con- 
trol string contains conversion specifications and other characters used to direct interpretation of input 
sequences. The control string contains: 

• White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the 
next non-white-space character (except in two cases described below). 

• An ordinary character (not %) that must match the next character of the input stream. 

• Conversion specifications, consisting of the character %, an optional assignment suppressing char- 
acter *, an optional numerical maximum-field width, an optional 1 (ell), h or L indicating the 
size of the receiving variable, and a conversion code. 

• The conversion specification can alternatively be prefixed by the character sequence %n $ instead 
of the character %, where n is a decimal integer in the range (1- {NL_ARGMAX}) (NL_ARGMAX is 
defined in <limits .h>). The %n$ construction indicates that the value of the next input field 
should be placed in the n.th argument, rather than to the next unused one. The two forms of intro- 
ducing a conversion specification, % and %n$, must not be mixed within a single format string 
with the following exception: Skip fields (see below) can be designated as %* or %n$*. In the 
latter case, n is ignored. 

Unless the specification contains the n conversion character (described below), a conversion specification 
directs the conversion of the next input field. The result of a conversion specification is placed in the 
variable to which the corresponding argument points, unless * indicates assignment suppression. 
Assignment suppression provides a way to describe an input field to be skipped. An input field is defined 
as a string of non-space characters; it extends to the next inappropriate character or until the field width, 
if specified, is exhausted. For all descriptors except [ and c, white space leading an input field is 
ignored. 

The conversion code indicates the interpretation of the input field; the corresponding pointer argument 
must be of a restricted type. For a suppressed field, no pointer argument is given. The following conver- 
sion codes are legal: 

% A single % is expected in the input at this point; no assignment is done. 

d A decimal integer is expected; the corresponding argument should be an integer 

pointer. 

u An unsigned decimal integer is expected; the corresponding argument should be an 

unsigned integer pointer. 

o An octal integer is expected; the corresponding argument should be an unsigned 

integer pointer. 
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x, X A hexadecimal integer is expected; the corresponding argument should be an unsigned 

integer pointer. The x and X conversion characters are equivalent. 

i An integer is expected; the corresponding argument should be an integer pointer. The 

value of the next input item, interpreted according to C conventions, will be stored; a 
leading implies octal, a leading Ox implies hexadecimal; otherwise, decimal is 
assumed. 

n Cause the total number of bytes (including white space) scanned since the function 

call to be stored; the corresponding argument should be an integer pointer. No input 
is consumed. The function return value does not include %n assignments in the count 
of successfully matched and assigned input items. 

e,E,f,g,G A floating-point number is expected; the next field is converted accordingly and stored 
through the corresponding argument, which should be a pointer to a float . The input 
format for floating-point numbers is an optionally signed string of digits, possibly con- 
taining a radix character, followed by an optional exponent field consisting of an E or 
an e, followed by an optional +, -, or space, followed by an integer. The conversion 
characters E and G behave the same as, respectively, e and g. 

C A character is expected; the corresponding argument should be a wchar_t pointer. 

The normal skip-over-white-space is suppressed in this case; to read the next non- 
space character, use %1S. The character is read and converted into a wide character 
according to the setting of LC_CTYPE. If a field width is given, the corresponding 
argument refers to a wide character array; the indicated number of characters is read 
and converted. 

c A character is expected; the corresponding argument should be a character pointer. 

The normal skip-over-white-space is suppressed in this case; to read the next non- 
space character, use %ls. If a field width is given, the corresponding argument refers 
to a character array; the indicated number of characters is read. 

S A character string is expected; the corresponding argument should be a wchar_t 

pointer pointing to an array of wide characters large enough to accept the string and a 
terminating (wchar_t)0, which is added automatically. Characters are read and 
converted into wide characters according to the setting of LC_CTYPE. The input field 
is terminated by a white-space character, scanf ( ) cannot read a null string. 

s A character string is expected; the corresponding argument should be a character 

pointer pointing to an array of characters large enough to accept the string and a ter- 
minating \0, which is added automatically. The input field is terminated by a white- 
space character, scanf ( ) cannot read a null string. 

[ Indicates string data and the normal skip-over-leading-white-space is suppressed. 

The left bracket is followed by a set of characters, called the scanset, and a right 
bracket; the input field is the maximal sequence of input characters consisting entirely 
of characters in the scanset. The circumflex ( A ), when it appears as the first character 
in the scanset, serves as a complement operator and redefines the scanset as the set of 
all characters not contained in the remainder of the scanset string. Construction of 
the scanset follows certain conventions. A range of characters may be represented by 
the construct first-last, enabling [0123456789] to be expressed [0-9]. Using this con- 
vention, first must be lexically less than or equal to last; otherwise, the dash stands 
for itself. The dash also stands for itself when it is the first or the last character in the 
scanset. To include the right square bracket as an element of the scanset, it must 
appear as the first character (possibly preceded by a circumflex) of the scanset, in 
which case it will not be interpreted syntactically as the closing bracket. The 
corresponding argument must point to a character array large enough to hold the data 
field and the terminating \0, which are added automatically. At least one character 
must match for this conversion to succeed. 

p A sequence of unsigned hexadecimal numbers is expected. This sequence may be pro- 

duced by the p conversion character of print f ( ) . The corresponding argument 
shall be a pointer to a pointer to void into which the value represented by the hexa- 
decimal sequence is stored. The behavior of this conversion is undefined for any input 
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item other than a value converted earlier during the same program execution. 

The conversion characters d, i, and n can be preceded by 1 or h to indicate that a pointer to a 
long int or short int rather than to an int is in the argument list. Similarly, the conver- 
sion characters u, o, x, and X can be preceded by lor h to indicate that a pointer to unsigned 
long int or unsigned short int rather than to an unsigned int is in the argument 
list. Finally, the conversion characters e, E, f , g, and G can be preceded by 1 or L to indicate that 
a pointer to a double or long double rather than to a float is in the argument list. The 
1, L or h modifier is ignored for other conversion characters. 

The scanf ( ) functions terminate their conversions at EOF, at the end of the control string, or 
when an input character conflicts with the control string. In the latter case, the offending character 
is left unread in the input stream. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of ordinary characters within format strings as 
single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the 
input stream are interpreted as single- or multi -byte characters as determined by the LC_TYPE category 
and the field width is decremented by the length of the character. 

The LC_NUMERIC category determines the radix character expected within floating-point numbers. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUES 

If the input ends before the first conflict or conversion, EOF is returned. Otherwise, these functions return 
the number of successfully assigned input items. This number is a short count, or even zero if a conflict 
ensues between an input character and the control string. 

ERRORS 

scanf ( ) , f scanf ( ) , nl_scanf ( ) , and nl_f scanf ( ) fail if data needs to be read into the stream's 
buffer, and: 

[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the process 

would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data 

was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its 

controlling terminal, and either the process is ignoring or blocking the SIGTTIN sig- 
nal or the process group of the process is orphaned. 

Additional errno values can be set by the underlying read ( ) function (see read(2J). 

EXAMPLES 

The call: 

int i, n; float x; char name [50]; 
n = scanf {"%&%f%s" , &i, &x, name); 

with the input line: 

25 54.32E-1 thompson 

assigns to re the value 3, to i the value 25, to x the value 5 .432, and name contains thompson\0. Or: 

int i; float x; char name [50]; 

(void) scanf ("%2d%f%*d %[ 0-9] ", &i, &x, name); 

with input: 

56789 0123 56a72 

assigns 56 to i, 789.0 to x, skips 0123, and places the string 56 \0 in name. The next call to 
get char ( ) (see getc(3S)) returns a. 
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For another example, to create a language-independent date scanning routine, use: 

char month [2 0]; int day, year; 

(void) scanf (format, month, &day, fcyear) ; 

For American usage, format would point to a string: 

%l$s %2$d %3$d 
The input: 

July 3 1986 
would assign July to month, 3 to day and 1986 to year. 
For German usage, format would point to a string: 

%2$d %l$s %3$d 
The input: 

3 Juli 1986 

would assign Jul! to month, 3 to day and 1986 to year. 

The success of literal matches and suppressed assignments can be determined with the %n conversion 
specification. Here is an example that checks the success of literal matches: 

int i, nl, n2, n3, n4; 

nl = n2 = n3 = n4 = -1;" 

scanf ( "%nBEGIN%n %d %nEND%n", &nl, &n2, &i, &n3, &n4); 

if (n2 - nl == 5) puts ( "matched BEGIN"); 

if (n4 - n3 == 3) puts ( "matched END"); 

Here is an example that checks the success of suppressed assignments: 

int i, nl, n2; 

nl = n2 = -1; 

scanf ( "%& %n%*s%n", &i, &nl, &n2); 

if (n2 > nl) 

printf ( "successful assignment suppression of %d chars\n", n2 - nl); 

WARNINGS 

Trailing white space (including a newline) is left unread unless matched in the control string. 

Truncation of multi-byte characters may occur if a field width is used with the conversion character. 

nl_scanf ( ) , nl_f scanf ( ) , and nl_sscanf ( ) are provided for historical reasons only. Their use is 
not recommended. Use scanf ( ) , f scanf ( ) , and s scanf ( ) instead. 

AUTHOR 

scanf ( ) was developed by AT&T and HP. 

SEE ALSO 

getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). 

STANDARDS CONFORMANCE 

scanf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
f scanf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

nl_f scanf ():XPG2 
nl_scanf ():XPG2 

nl_s scanf ( ) : XPG2 

sscanf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

setaclentry(), fsetaclentryO - add, modify, or delete one entry in file's access control list (ACL) 

SYNOPSIS 

#include <unistd.h> 
#include <acllib.h> 

int setacl entry (const char *path, int uid, int gid, int mods); 

int fsetaclentry (Int fd, int uid, int gid, int mode); 

DESCRIPTION 

Both forms of this call add, modify, or delete one entry in a file's access control fist (ACL), setaclen- 
try() and fsetaclentryO take a path name (path) or open file descriptor (fd) and an entry 
identifier (uid, gid). They change the indicated entry's access mode bits to the given value (mode), mean- 
ings of which are defined in <unistd.h>. modes are represented as R_OK, W_OK, and X_OK. Irrelevant 
bits in mode values must be zero. 

If the file's ACL does not have an entry for the given uid and gid, the entry is created and added to the ACL. 
If mode is MODE_DEL (defined in <ac 1 1 ib . h>), the matching entry is deleted from the file's ACL if it is 
an optional entry, or its mode bits are set to zero (no access) if it is a base entry. 

uid or gid can be ACL_NSUSER or ACL_NSGROUP (defined in <sys/acl . h>), respectively, to represent 
non-specific entries u .%, %.g, or %.% . The file's u .% or %.g base entries can be referred to using 
ACL_PILEOWNER or ACL_PILEGROUP (defined in <acllib.h>), for the file's owner or group ID, 
respectively. 

setaclentry() and fsetaclentryO read the file's ACL with getacl () or f getacl () and 
modify it with setacl ( ) or f setacl ( ) , respectively. 

RETURN VALUE 

If successful, setaclentryO and fsetaclentryO return zero. 

ERRORS 

If an error occurs, setaclentry ( ) and fsetaclentry ( ) return the following negative values and 
set errno: 

-1 Unable to perform getacl ( ) or f getacl ( ) on the file, errno indicates the cause. 

-2 Unable to perform stat () or fstat() on the file, errno indicates the cause. 

-3 Cannot add a new entry because the ACL already has NACLENTRIES (defined in <sys/acl.h>) 
entries. 

-4 Cannot delete a nonexisting entry. 

-5 Unable to perform setacl () or f setacl () on the file, errno indicates the cause. 

EXAMPLES 

The following code fragment adds an entry to file "work/list" for user ID 115, group ID 32, or modifies the 
existing entry for that user and group, if any, with a new access mode of read only. It also changes the 
owner base entry to have all access rights, and deletes the entry, if any, for any user in group 109. 

#include <unistd.h> 
#include <acllib.h> 

char ^filename = "work/list"; 

setaclentry (filename, 115, 32, R_OK) ; 

setaclentry (filename, ACL_PILEOWNER, ACL_NSGROUP, R_OK I W_OK | X_OK) ; 

setaclentry (filename, ACL_NSUSER, 109, MODE_DEL) ; 

DEPENDENCIES 

NFS setaclentryO and fsetaclentryO are not supported on remote files. 

AUTHOR 

setaclentryO and fsetaclentryO were developed by HP. 

SEE ALSO 

getacl(2), setacl(2), stat(2), acltostr(3C), cpacl(3C), chownacl(3C), strtoacl(3C), acl(5). 
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NAME 

setbuf(), setvbuf() - assign buffering to a stream file 

SYNOPSIS 

ttinclude <stdio.h> 

void setbuf(PILE ♦stream, char *buf); 

int setvbuf(FILE ♦stream, char *buf, int type, size_t size); 

DESCRIPTION 

setbuf ( ) can be used after a stream has been opened but before it is read or written. It causes the array 
pointed to by buf to be used instead of an automatically allocated buffer. If buf is the NULL pointer 
input/output will be completely unbuffered. 

A constant BUPSIZ, defined in the <stdio . h> header file, tells how big an array is needed: 

char buf [BUPSIZ] ; 

setvbuf ( ) can be used after a stream has been opened but before it is read or written, type determines 
how stream is to be buffered. Legal values for type (defined in <stdio . h>) are: 

_IOFBF causes input/output to be fully buffered. 

_IOLBP causes output to be fine buffered; the buffer will be flushed when a newline is written, 
the buffer is full, or input is requested. 

_IONBP causes input/output to be completely unbuffered. 

When an output stream is unbuffered, information is queued for writing on the destination file or terminal 
as soon as written; when it is buffered, many characters are saved up and written as a block. When the out- 
put stream is line-buffered, each line of output is queued for writing on the destination terminal as soon as 
the line is completed (that is, as soon as a new-line character is written or terminal input is requested), 
f f lush ( ) can also be used to explicitly write the buffer. 

If buf is not the NULL pointer, the array it points to is used for buffering instead of an automatically allo- 
cated buffer (from malloc ( ) ). size specifies the size of the buffer to be used. The constant BUFSIZ in 
<stdio .h> is suggested as a good buffer size. If input/output is unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other input/output is fully buffered. 

SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 

DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf () returns a non-zero value. Otherwise, the value 
returned will be zero. 

NOTE 

A common source of error is allocating buffer space as an "automatic" variable in a code block, then failing 
to close the stream in the same block. 

STANDARDS CONFORMANCE 

setbuf ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 

setvbuf ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 



HP-UX Release 9.0: August 1992 - 1 - 743 



I 



setclock(3C) setclock(3C) 



NAME 

setclock - set value of system-wide clock 

SYNOPSIS 

#include <sys/timers .h> 

int setclock(int clock_type, struct timespec *tp) ; 

DESCRIPTION 

setclock ( ) sets the current value tp of the specified system-wide clock, clockjype. 

setc lock ( ) supports a clockjype of TIMEOPDAY, defined in <sys /t inter s . h>, which represents the 
time-of-day clock for the system. For this clock, the values returned by setclock () represent the 
amount of time since the Epoch. 

The calling process must have appropriate privileges to set the TIMEOPDAY clock. 

RETURN VALUE 

setclock( ) returns a value of zero if successful; otherwise it returns -1 and sets errno to indicate the 
error. 

ERRORS 

setclockQ fails if any of the following conditions are encountered: 

[EINVAL] clockjype does not specify a known system-wide clock, or tp either is outside the 

range for a given clock type, or specifies a nanosecond value less than zero or greater 
than or equal to 1000 million. 

[EIO] An error occurred while accessing the clock device 

[EPERM] The requesting process does not have the required appropriate privileges to set the 

specified clock. 

SEE ALSO 

gettimer(3C), getclock(3C), <sys/timers.h> 

STANDARDS CONFORMANCE 

setclock():AES 
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NAME 

setjmp(), longjmpO, sigsetjmpO, siglongjmp( ) - non-local goto 

SYNOPSIS 

ttinclude <setjmp.h> 

int setjmp (jmp_buf env) ; 

void longjmp( jmp_buf env, Int val); 

int _setjmp( jmp_buf env); 

void _long jmp ( jmp_buf env, int val); 

int sigset jmp(sigjmp_buf env, int savemask) ; 

void siglongjmp(sigjmp_buf env, int val); 

DESCRIPTION 

setjmp ( ) and long jmp ( ) are useful for dealing with errors and interrupts encountered in a low-level 
subroutine of a program. They exist in three variant forms: setjmp ( ) and longjmp ( ) ; _set jmp ( ) 
and _longjmp(); sigsetjmpO and siglongjmp( ). Unless indicated otherwise, references to 
setjmp () and longjmpO apply to all three versions. 

setjmp () saves its stack environment in env (whose type, jmp_buf, is defined in the 

<set jmp . h> header file) for later use by longjmp ( ) . It returns the value 0. 

longjmpO restores the environment saved by the last call of setjmp () with the 

corresponding env argument. After longjmpO is completed, program execution 
continues as if the corresponding call of setjmp ( ) (which must not itself have 
returned in the interim) had just returned the value val. longjmp ( ) cannot 
cause setjmp ( ) to return the value 0. If longjmp ( ) is invoked with a 
second argument of 0, setjmp ( ) returns 1. All accessible data values are valid 
as of the time longjmpO is called. 

Upon the return from a setjmp ( ) call caused by a longjmp ( ) , the values of any non-static local vari- 
ables belonging to the routine from which setjmp ( ) was called are undefined. Code which depends on 
such values is not guaranteed to be portable. 

Variant Forms 

The following functions behave the same as setjmp () and longjmpO except in the handling of the 
process' signal mask (see sigaction(2) and sigvector(2)). This distinction is only significant for programs 
which use sigactionO, sigprocmaskO, sigvector (), sigblock(), and/or sigsetmask( ). 

setjmp ( ) 

longjmp ( ) These always save and restore the signal mask. 

_setjmp() 

_long jmp ( ) These never manipulate the signal mask. 

sigset jmp ( ) Saves the signal mask if and only if savemask is non-zero. 

s i gl ong j mp ( ) Restores the signal mask if and only if it is saved by s i gs et jmp ( ) . 

Programming Considerations 

If a longjmp ( ) is executed and the environment in which the setjmp ( ) is executed no longer exists, 
errors can occur. The conditions under which the environment of the setjmp ( ) no longer exists include 
exiting the procedure that contains the setjmp ( ) call, and exiting an inner block with temporary storage 
(such as a block with declarations in C or a with statement in Pascal). This condition might not be detect- 
able, in which case the longjmp ( ) occurs and, if the environment no longer exists, the contents of the 
temporary storage of an inner block are unpredictable. This condition might also cause unexpected process 
termination. If the procedure has been exited the results are unpredictable. 

Passing longjmp ( ) a pointer to a buffer not created by setjmp ( ) , passing _long jmp ( ) a pointer to 
a buffer not created by either setjmp ( ) or _set jmp ( ) , passing siglong jmp ( ) a pointer to a buffer 
not created by sigset jmp ( ) or passing any of these three functions a buffer that has been modified by 
the user, can cause all the problems listed above, and more. 
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Some implementations of Pascal support a "try/recover" mechanism, which also creates stack marker infor- 
mation. If a longjmp ( ) operation occurs in a scope which is nested inside a try/recover, and the 
corresponding set jmp ( ) is not inside the scope of the try/recover, the recover block will not be executed 
and the currently active recover block will become the one enclosing the set jmp ( ) , if one exists. 

WARNINGS 

A call to longjmp ( ) to leave the guaranteed stack space reserved by sigspace ( ) might remove the 
guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might 
also cause the program to forever lose its ability to automatically increase the stack size, and the program 
might then be limited to the guaranteed space. 

The result of using set jmp ( ) within an expression can be unpredictable. 

If longjmp ( ) is called even though env was never primed by a call to set jmp ( ) , or when the last such 
call was in a function that has since returned, total chaos is guaranteed. 

AUTHOR 

set jmp ( ) was developed by AT&T and HP. 

SEE ALSO 

sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). 

STANDARDS CONFORMANCE 

set jmp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
longjmp ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

slglongjmp ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
sigset jmp ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

setlocale(), getlocale() - set and get the locale of a program 

SYNOPSIS 

ttinclude <locale.h> 

char *setlocale(int category, const char *locale); 
struct locale_data *getlocale(int type); 

DESCRIPTION 

setlocale() sets, queries or restores that aspect of a program's locale as specified by the category argu- 
ment. A program's locale refers to those areas of the program's Native Language Support (NLS) environ- 
ment for which the following values of category have been defined: 

LC_ALL Affects behavior of all categories below as well as all nl_langinfo(3C) items. 

Note that some nljanginfo items are only affected by the setting of the 
LC_ALL category. 

LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions 

(see string(3C) and regexp(5)). 

LC_CTYPE Affects behavior of regular expressions, character classification and conversion 

functions (see ctype(3C), conv(3C), and regexp(5)). The LC_CTYPE category 
also affects the behavior of all routines that process multibyte characters (see 
multibyte(3C) and nl_tools_16(3C)). 

LC_MES SAGES Affects the language in which messages are displayed and the processing of 

affirmative and negative responses. 

LC_MONETARY Affects behavior of functions that handle monetary values (see localeconv (3C)). 

LC_NUMERIC Affects handling of the radix character in the formatted input/output functions 

(see printf(3C), scanf(3C) and vprintf(3C)) and the string conversion functions 
(see ecvt(3C) and strtod (3C)). LC_NUMERIC also affects the numeric values 
found in the localeconv structure. 

LC_TIME Affects the behavior of time conversion functions (see getdate(3C) and 

strftime(3Q). 

All nl_langinfo(3C) items are affected by the setting of one of the categories listed above. See lan- 
ginfo(5) to determine which categories affect each item. 

The value of the locale argument determines the action taken by set locale ( ) . locale is a pointer to a I 

character string. ^ 

Setting the Locale of a Program 

To set the program's locale for category, set locale ( ) accepts one of the following values as the locale 
argument: locale name, "C", or "" (the empty string). The actions prescribed by these values are as follows 

locale name If locale is a valid locale name (see lang(5)), set locale ( ) sets that part of the NLS 
environment associated with category as denned for that locale. 

"C" If the value of locale is set to "C", setlocale() sets that part of the NLS environment 

associated with category as defined for the "C" locale (see lang(5)). The "C" locale is the 
default prior to successfully calling set locale ( ) . 

POSIX Same as "C" 

If the value of locale is the empty string, the setting of that part of the NLS environment 
associated with category depends on the setting of the following environment variables in 
the user's environment (see environ(5)): 

LANG LC_MESSAGES 

LC_ALL LC_MONETARY 

LC_COLLATE LC_NUMERIC 

LC_CTYPE LC_TIME 
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If category is any defined value other than LC_ALL, set locale ( ) sets that category as specified by the 
value of the LC_ALL environment or if LC_ALL is not set to the corresponding environment variable. If 
the environment variable is not set or set to the empty string, setlocale() sets the category as 
specified by the value of the LANG environment variable. If LANG is not set or is set to the empty string, 
then setlocale() sets the category to the "C" locale. For example, setlocale (LC_TIME -" ") 
sets the program's NLS environment associated with the LC_TIME category to the value specified by the 
user's LC_TIME environment variable. All other aspects of the NLS environment are unaffected. 

If category is LC_ALL, then all categories are set corresponding to the value of LC_ALL if LC_ALL is 
set, or LANG if LC_ALL is not set, except for those categories in which the corresponding environment 
variable is set to a valid language name (see lang(5)). In this case the value of the environment variable 
overrides the values of LC_ALL and LANG for that category. If the values of both LC_ALL and LANG 
are not set or are set to the empty string, then the "C" locale is used. 

The following usage of set locale ( ) results in the program's locale being set according to the the user's 
language requirements: 

setlocale (LC_ALL, " " ) ; 

Querying the Locale of a Program 

setlocale ( ) queries the current NLS environment pertaining to category if the value of locale is NULL. 
The query operation does not change the environment. The purpose of performing a query is to save that 
aspect of the user's current NLS environment associated with category, in the value returned by setlo- 
cale ( ) , such that it can be restored with a subsequent call to setlocale ( ) . 

Restoring the Locale of a Program 

To restore a category within the program locale, a setlocale ( ) call is made with the same category 
argument and the return string of the previous setlocale ( ) call given as the locale argument. 

get locale ( ) returns a pointer to a locale_data structure (see /usr/include/locale . h). The 
members of the locale_data structure contain information about the setting of each setlocale category. 
type determines what information is contained in the locale_data structure. Defined values of type 
and their behaviour are : 

LOCALE_STATUS The structure member corresponding to each category contains a string 

with the name of the locale currently set for that category. The string does 
not include modifier information. 

MODIPIER_STATUS The structure member corresponding to each category contains a string 
with the name of the modifier currently set for that category. If no 
modifier is set then the entry contains an empty string. 

ERROR_STATUS The structure member contains information about errors which occurred 

during the previous call to setlocale(). If setlocale () could not 
satisfy a request corresponding to a particular category, the structure 
member for that category contains a string with the name of the invalid 
locale. In all other cases the member for the category contains an empty 
string. 

RETURN VALUE 

If the pointer to a string is given for locale and the selection can be honored, the setlocale ( ) function 
returns a pointer to the string associated with the specified category for the new locale. The maximum 
length of this string is LC_BUPSIZ bytes (see <locale.h>). If the selection cannot be honored, the 
setlocale ( ) function returns a null pointer and the program's locale is not changed. 

A null pointer for locale causes setlocale () to return a string associated with the category for the 
program's current locale. 

The string returned by setlocale ( ) is such that a subsequent call with that string as the locale argu- 
ment and its associated category restores that part of the program's locale. 

ERRORS 

If a language name given through the locale argument does not identify a valid language name or the 
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language is not available on the system (see lang(5)) a null pointer is returned and the program's locale is 
not changed. The same behavior occurs when the call : 

setlocale (LC_ALL # " " ) ; 

is made and any category related environment variable in the user's environment identifies an invalid 
language name or a language that is not available on the system. 

If the category argument is not a defined category value, a null pointer is returned and the program's locale 
is not changed. 

setlocale ( ) returns a string which reflects the current setting of that aspect of the NLS environment 
corresponding to the category argument. If this return string is used in a subsequent setlocale () call 
and the category arguments of the two calls do not match, the locale remains unchanged and a null pointer 
is returned. 

WARNINGS 

Using getenvO as the locale argument is not recommended. An example of such incorrect usage is : 

setlocale (LC_ALL, getenv("LANG" ) ) ; 

getenv ( ) returns a character string which can be a language name, an empty string, or a null pointer; 
depending on the setting of the user's LANG environment variable. Each of these values as the locale argu- 
ment define a specific action to be taken by setlocale (). Therefore the action taken by setlo- 
cale () depends upon the value returned from the getenvO call. To ensure that setlocale () sets 
the program's locale based upon the setting of the user's environment variables the following usage is 
recommended: 

setlocale (LC_ALL, " " ) ; 

The value returned by setlocale() points to a static area that is overwritten during the next call to 
setlocale ( ) . Be sure to copy these values to another area if they are to be used after a subsequent 
setlocale () call. 

The structure returned through a call to getlocale ( ) is overwritten during the next call to getlo- 
cale ( ) . Be sure to save these values if they are to be used after a subsequent getlocale ( ) call. 

Any program which calls setlocale ( ) before catopen ( ) may behave differently in this release than 
on previous releases because of the addition of LC_MES SAGES to XPG4 .In the past, catopen () was 
directed to the desired language by LANG . Now, catopen () is controlled by LC_MESSAGES . 
Setlocale ( ) can modify the LC_MESSAGES category. 

For example, if the environment variables are set as follows : 

LC_MESSAGES= "f rench" 
and the following call to set locale () is made: 

setlocale (LC_ALL, "gentian"); 

which is followed by a call to catopen ( ) . Catopen ( ) will open the message catalogs for german 
rather than f rench. 

EXAMPLES 

To set a program's entire locale based on the language requirements specified via the user's environment 
variables : 

setlocale (LC_ALL, " " ) ; 

If, in the previous example, the user's environment variables were set as follows : 

LANG ="german" 

LC_COLLATE =" span! sh@nof old" 

LC_MONETARY ="" 

LC_TIME ="american" 

the LC_ALL, LC_CTYPE, LC_MONETARY, and LCJNUMERIC category items would be set to correspond 
to the german language definition, the LC_COLLATE category items would be set to correspond to the 
Spanish language definition for unfolded collation (see hpnls(5)) and the LC_TIME category items would 
be set corresponding to the amer lean language definition. 
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Using the same example, if the following call was made: 

struct locale_data *locale_info=get locale (LOCALE_STATUS ) ; 

the contents of *locale_inf o would be : 

locale_info->LC_ALL_D="german" 

locale_lnfo->LC_COLLATE_D=" Spanish" 

locale_info->LC_CTYPE_D="german" 

locale_lnfo->LC_MESSAGES_D="german" 

locale_lnfo->LC_MONETARY_D="german" 

locale_lnfo->LC_NUMERIC_D="german" 

locale_lnfo->LC_TIME_D="american" 

Continuing with the same example, if the following call was made : 

struct locale_data *modifier_info=get locale (MODIFIER_STATUS) ; 

the contents of *modifier_info would now be : 

modlf ler_lnf o->LC_ALL_D=" " 
modlfier_info->LC_COLLATE_D="nofold" 
modif ler_inf o->LC_CTYPE_D=" " 
modlf ler_inf o->LC_MESSAGES_D= " " 
modlf ler_info->LC_MONETARY_D= " " 
modif ier_info->LC_NUMERIC_D=" " 
modifier_info->LC_TIME_D="" 

The calls : 

set locale (LC_ALL, " " ) ; 

struct locale_data *error_inf o=getlocale(ERROR_STATUS) ; 

with the following settings in the users environment : 

LANG=german 
LC_COLLATE=junk 

where junk is an invalid language, would result in the contents of *error_inf o being: 

_error_inf o->LC_ALL_D=" " 
_error_info->LC_COLLATE_D=" junk" 
_error_inf o->LC_CTYPE_D=" " 
_error_inf o->LC_MESSAGES_D= " " 
_error_inf o->LC_MONETARY_D= " " 
_error_inf o->LC_NUMERIC_D=" " 
_error_inf o->LC_TIME_D= " " 

An example showing the precedence of the LC_ALL environment variable : 

setlocale (LC_ALL, " " ) ; 

with the following settings in the users environment : 

LANG=german 
LC_ALL= f r ench 

All categories will be loaded with f rench . 

Another example showing the precedence of the LC_ALL environment variable : 

setlocale (LC_CTYPE, " " ) ; 

with the following settings in the users environment : 

LANG=turkish 
LC_ALL=dani sh 
LC_CTYPE=russian 

The LC_CTYPE category will be loaded with dani sh . 
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Another example with the LC_ALL environment variable : 

setlocale (LC_TIME, "polish"); 

with the following settings in the users environment : 

LANG= Italian 
LC_ALL=dutch 

The LC_TIME category will be set to pol ish . 

To set the date/time formats to French : 

setlocale (LC_TIME, "f rench" ) ; 
To set the collating sequence to the "C" locale : 

setlocale ( LC_COLLATE, "C"); 
To set monetary handling to the value of the user's LC_MONETARY environment variable : 

setlocale ( LC_MONETARY, " " ) / 

(Note that if the LC_MONETARY environment variable is not set or empty, the value of the user's LANG 
environment variable is used.) 

To query a user's locale: 

char *ch = setlocale ( LC_ALL, NULL); 
To restore the locale saved in the above example : 

setlocale (LC_ALL, ch) ; 
To query just that part of the user's locale pertaining to the LC_NUMERIC category : 

char *ch = setlocale (LC_NUMERIC, NULL); 
To restore the LC_NUMERIC category of the user's locale saved in the above example : 

setlocale (LC_NUMERIC, ch) ; 

AUTHOR 

setlocale ( ) was developed by HP. 

SEE ALSO 

nlsinfo(l), buildlang(lM), conv(3C), ctype(3C), ecvt(3C), getdate(3C), langinfo(3C), multibyte(3C), ■ 

nl_tools_16(3C), printf(3S), scanf(3S), strcoll(3C), strftime(3C), string(3C), strtod(3C), vprintf(3S), I 

wconv(3X), wctype(3X), wstring(3X), hpnls(5), environ(5), langinfo(5), strerror(3C), <langinfo.h>, <locale.h>. ■ 

STANDARDS CONFORMANCE 

setlocale ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

shl_load(), shl_definesym(), shl_findsym(), shl_gethandle(), shl_getsymbols( ), shl_unload(), shl_get() - 
explicit load of shared libraries 

SYNOPSIS 

#include <dl.h> 

shl_t shl_load (const char *path, int flags, long address); 

int shl_findsym( 

shl_t *handle, 

const char *sym, 

short type, 

void * value 
); 

int shl_def inesym( 

const char *sym, 

short type , 

long value, 

int flags 
); 
int shl_getsymbols ( 

shl_t handle, 

short type , 

int flags, 

void *(*memory) (), 

struct shl_symbol **symbols, 
); 

int shl_unload(shl_t handle); 

int shl_get(int index, struct shl_descriptor **desc); 

int shl_gethandle(shl_t handle, struct shl_descriptor **desc); 

DESCRIPTION 

These routines can be used to programmatically load and unload shared libraries, and to obtain informa- 
tion about the libraries (such as the addresses of symbols defined within them). The routines themselves 
are accessed by specifying the - ldld option on the command line with the cc or Id command (see cc(l) 
and ld(l)). In addition, the -E option to the Id command can be used to ensure that all symbols defined 
in the program are available to the loaded libraries. 

Shared libraries are created by compiling source files with the + z (position -independent code) option, and 
finking the resultant object files with the -b (create shared library) option. 

shl_load ( ) Attaches the shared library named by path to the process. The library is mapped at 

the specified address. If address is OL, the system chooses an appropriate address for 
the library. This is the recommended practice because the system has the most com- 
plete knowledge of the address space (see DEPENDENCIES). The flags argument is 
made up of several fields. One of the following must be specified: 

BIND_IMMEDIATE Resolve symbol references when the library is loaded. 

BIND_DEPERRED Delay code symbol resolution until actual reference. 

Zero or more of the following can be specified by doing a bitwise OR operation: 

BIND_PIRST Place the library at the head of the symbol search order. 

BIND_NONPATAL Default BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as 
fatal. This flag allows binding of unsatisfied code symbols to be deferred 
until use. 

BIND_NOSTART Do not call the initializer for the shared library when the library is loaded, 

nor on a future call to shl_unload ( ) . 
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BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. 

If successful, shl_load() returns a handle which can be used in subsequent calls to 
shl_f indsym ( ) , shl_unload ( ) , or shl_gethandle ( ) ; otherwise NULL is returned. 

shl_f indsym () 

Obtains the address of an exported symbol sym from a shared library. The handle argument should be a 
pointer to the handle of a loaded shared library that was returned from a previous call to shl_load ( ) 
or shl_get(). If a pointer to NULL is passed for this argument, shl_f indsym ( ) searches all 
currently loaded shared libraries to find the symbol; otherwise shl_f indsym ( ) searches only the 
specified shared library. The return value of handle will be NULL if the symbol found was generated via 
shl_def inesym( ) . Otherwise the handle of the library where the symbol was found is returned. The 
special handle PROG_HANDLE can be used to refer to the program itself, so that symbols exported from 
the program can also be accessed dynamically. The type argument specifies the expected type for the sym- 
bol, and should be one of the defined constants TYPE_PROCEDURE, TYPE_DATA, or TYPE_UNDEFINED. 
The latter value suppresses type checking. The address of the symbol is returned in the variable pointed 
to by value. If a shared library contains multiple versions of the requested symbol, the latest version is 
returned. This routine returns if successful; otherwise -1 is returned. 

shl_def inesym( ) 

Adds a symbol to the shared library symbol table for the current process making it the most visible 
definition. If the value falls in the range of a currently loaded library, an association will be made and the 
symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a 
subsequent call to this routine or by loading a more visible library that provides a definition. Symbols 
overridden in this manner may become visible again if the overriding definition is removed. 

Possible symbol types include: 

TYPE_PROCEDURE Symbol is a function. 
TYPE_DATA Symbol is data. 

Possible flag values include: None defined at the present time. Zero should be passed in to prevent 
conflicts with future uses of this flag. 

shl_getsymbols ( ) 

Provides an array of symbol records, allocated using the supplied memory allocator, that are associated 
with the library specified by handle. If the handle argument is a pointer to NULL, symbols defined using 
shl_def inesymC) are returned. If multiple versions of the same symbol have been defined within a 
library or with shl_de fine sym ( ) , only the version from the specified symbol information source that 
would be considered for symbol binding is returned. The type argument is used to restrict the return infor- 
mation to a specific type. Values of TYPE_PROCEDURE and TYPE_DATA can be used to limit the 
returned symbols to be either code or data respectively. The constant TYPE_UNDEFINED can be used to 
return all symbols, regardless of type. The flags argument must have one of the following values: 

IMPORT_SYMBOLS 

Return symbols found on the import list. 

EXPORT_SYMBOLS 

Return symbols found on the export list. All symbols defined via 
shl_def inesym ( ) are export symbols. 

Zero or more of the following can be specified by doing a bitwise OR operation: 

NO_VALUES Only makes sense when combined with EXPORT_SYMBOLS. Do not calculate the 
value field in the return structure to avoid symbol binding by the loader to resolve 
symbol dependencies. If only a few symbol values are needed, shl_f indsym () 
can be used to find the values of interesting symbols. Not to be used with 
GLOBAL_VALUES. 

GLOBALJVALUES 

Only makes sense when combined with EXPORT_SYMBOLS. Use the name and 
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type information of each return symbol and find the most visible occurrence using all 
symbol information sources. The value and handle fields in the symbol return struc- 
ture reflect where the most visible occurrence was found. Not to be used with 
NOJVALUES. 

The memory argument should point to a function with the same interface as ma Hoc ( ) (see malloc(3C)). 

The return information consists of an array of the following records (defined in <dl .h>): 

struct shl_symbol { 

char *name, 

short type, 

void value, 

shl_t handle, 
}; 

The type field in the return structure can have the values TYPE_PROCEDURE, TYPE_DATA, or 
TYPE_STORAGE, where TYPE_STORAGE is a subset of TYPE_DATA. The value and handle fields are 
only valid if export symbols are requested and the NO_VALUES flag is not specified. The value field con- 
tains the address of the symbol, while the handle field is the handle of the library that defined the symbol, 
or NULL for symbols defined via the shl_def lnesym( ) routine and is useful in conjunction with the 
GLOBAL_VALUES flag. 

If successful, shl_get symbols ( ) returns the number of symbols found; otherwise it returns -1. 

shl_unload() 

Can be used to detach a shared library from the process. The handle argument should be the handle 
returned from a previous call to shl_load ( ) . shl_unload ( ) returns if successful; otherwise -1 is 
returned. All explicitly loaded libraries are detached automatically on process termination. 

shl_get ( ) 

Returns information about currently loaded libraries, including those loaded implicitly at startup time. 
The index argument is the ordinal position of the shared library in the shared library search list for the 
process. A subsequent call to shl_unload() decrements the index values of all libraries having an 
index greater than the unloaded library. The index value -1 refers to the dynamic loader. The desc argu- 
ment is used to return a pointer to a statically allocated buffer containing a descriptor for the shared 
library. The format of the descriptor is implementation dependent; to examine its format, look at the con- 
tents of file /usr/lnclude/dl .h. Information common to all implementations includes the library 
handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by 
shl_get ( ) is static; the contents should be copied elsewhere before a subsequent call to the routine. The 
routine returns normally, or -1 if an invalid index is given. 

shl_gethandle ( ) 

Returns information about the library specified by the handle argument. The special handle 
PROG__HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one 
returned by the shl_get ( ) routine. The buffer for the descriptor used by shl_gethandle ( ) is 
static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 
normally, or -1 on error. 

DIAGNOSTICS 

If a library cannot be loaded, shl_load ( ) returns NULL and sets errno to indicate the error. All other 
functions return -1 on error and set errno. 

If shl_f indsym( ) cannot find the indicated symbol, errno is set to zero. If shl_f IndsymO finds 
the indicated symbol but cannot resolve all the symbols it depends on, errno is set to ENOSYM. 

If a call to shl__load( ) or shl_f lndsym( ) fails with ENOSYM, the process may be left in an incon- 
sistent state. Some symbol resolutions may have occurred before the failure, and these may be invalid. 
The program should probably be terminated if this occurs. 
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ERRORS 

Possible values for errno include: 

[ENOEXEC] The specified file is not a shared library, or a format error was detected. 

[ENOSYM] Some symbol required by the shared library could not be found. 

[EINVAL] The specified handle or index is not valid or an attempt was made to load a library at 

an invalid address. 

[ENOMEM] There is insufficient room in the address space to load the library. 

[ENOENT] The specified library does not exist. 

[EACCES] Read or execute permission is denied for the specified library. 

WARNINGS 

shl_unload ( ) detaches the library from the process and frees the memory allocated for it, but does not 
break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a 
block of memory deallocated via free() (seefree(3C)). 

Some implementations may not, by default, export all symbols defined by a program (instead exporting only 
those symbols that are imported by a shared library seen at link time). Therefore the -E option to ld(l) 
should be used when using these routines if the loaded libraries are to refer to program symbols. 

All symbol information returned by shl_getsymbols ( ) , including the name field, become invalid once 
the associated library is unloaded by shl_unload ( ) . 

DEPENDENCIES 
Series 300/400: 

shl_def inesym() and shl_getsymbols () are not implemented on Series 300 and 400 systems. 

When using shl_f indsym ( ) , keep in mind that the compilers place an underscore at the beginning of all 
external names. 

Series 700/800: 

The only value for the address field is OL. Any other value is treated as if it had been specified as OL. 

The following additional values for the flags argument can be used with shl_load ( ) on Series 700 and 
800 systems: 

BIND_RESTRICTED 

Restrict symbols visible by the library to those present at library load time. 

DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the path argu- ■ 

ment. The directories to be searched are determined by the +s and +b options * 

of the Id command used when the program was linked. 

AUTHOR 

shl_load(SX) and related functions were developed by HP. 

SEE ALSO 

ld(l), dld.sl(5). 



HP-UX Release 9.0: August 1992 - 4 - 755 



I 



sigsetops(3C) sigsetops(3C) 



NAME 

sigemptyset(), sigfillset(), sigaddsetQ, sigdelset(), sigismemberO - initialize, manipulate, and test signal 
sets 

SYNOPSIS 

#include <signal.h> 

int sigemptyset (sigset_t *set) ; 

int sigf illset (sigset_t *set); 

int sigaddset (slgset_t *set, int signo); 

int sigdelset (sigset_t *set, int signo); 

int sigismember (const sigset_t *set, int signo); 

DESCRIPTION 

sigemptyset ( ) initializes the signal set pointed to by set, to exclude all signals supported by HP-UX. 

sigfillset() initializes the signal set pointed to by set, to include all signals supported by HP-UX. 

Applications must call either sigemptyset ( ) or sigfillset() at least once for each object of type 
sigset_t before using that object for anything else, including cases where the object is returned from a 
function (for example, the oset argument to s igprocmask ( ) — see sigprocmask(2)). 

sigaddset ( ) adds the signal specified by signo to the signal set pointed to by set . 

sigdelset ( ) deletes the signal specified by signo from the signal set pointed to by set, 

sigismember ( ) tests whether the signal specified by signo is a member of the signal set pointed to by 
set. 

RETURN VALUE 

Upon successful completion, sigismember ( ) returns a value of 1 if the specified signal is a member of 
the specified set, or a value of if it is not. The other functions return a value of upon successful comple- 
tion. For all of the above functions, if an error is detected, a value of-1 is returned and errno is set to 
indicate the error. 

ERRORS 

sigaddset ( ), sigdelset ( ), and sigismember ( ) fail if the following is true: 

[EINVAL] The value of the signo argument is out of range. The reliable detection of this error is 

not guaranteed. 

WARNINGS 

The above functions do not detect a bad address passed in for the set argument. A segmentation fault is the 
most likely result. 

AUTHOR 

sigf illset (), sigemptyset (), sigaddset (), sigdelset (), and sigismemberO were 
derived from the IEEE Standard POSIX 1003.1-1988 . 

SEE ALSO 

sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). 

STANDARDS CONFORMANCE 

sigaddset ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
sigdelset ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

sigemptyset ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
sigf illset () : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

sigismember ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

sinh(), cosh(), tanhQ, sinhf(), coshf(), tanhf() - hyperbolic functions 

SYNOPSIS 

ttinclude <math.h> 

double sinh(double x) ; 
double cosh(double x) ; 
double tanh(double x) ; 
float sinhf (float x) ; 
float coshf (float x) ; 
float tanhf (float x) ; 

DESCRIPTION 

slnh ( ) , cosh ( ) , and t anh ( ) return respectively the hyberbolic sine, cosine, and tangent of their argu- 
ment. 

When x is INFINITY, s inh ( ) returns INFINITY respectively. 

When x is INFINITY, cosh() returns +INFINITY. 

When x is INFINITY, tanh() returns ±1.0 respectively. 

sinhf (), coshf (), and tanhf ( ) are float versions of these functions. Their performance is 
significantly faster than that of the double versions. Programs must be compiled in ANSI mode (use the 
-Aa option) in order to use these functions; otherwise, the compiler promotes the float arguments to 
double, and the functions return incorrect results. 

DEPENDENCIES 
Series 300/400 

sinhf ( ) , coshf ( ) , and tanhf ( ) are not supported on Series 300/400 systems. 

Series 700/800 

sinhf (), coshf (), and tanhf ( ) are not specified by any standard (they are, however, named in 
accordance with the conventions specified in the "Future Library Directions" section of the ANSI C stan- 
dard). They are provided in the PAl.l versions of the math library only. The +DA1 . 1 option (the default 
on Series 700 systems) finks in a PAl.l version automatically. A PAl.l library can be linked in explicitly. 
For more information, see the HP-UX Floating-Point Guide . 

ERRORS 

/lib/libm.a 

sinh ( ) and cosh ( ) return HUGE_VAL (and sinh ( ) may return -HUGE_VAL for negative x) and set 
er mo to ERANGE when the correct value would overflow. 

sinh(), cosh() and tanh() return NaN and set errno toEDOM whenx isNaN. In addition, a mes- 
sage indicating DOMAIN error is printed on the standard error output. 

These error-handling procedures can be changed with the matherr ( ) function (see matherr(3M)). 

/Lib/libM.a 

No error messages are printed on the standard error output. 

sinh() and cosh() return HUGE_VAL (and sinh() may return -HUGE_VAL for negative x) and set 
errno to ERANGE when the correct value would overflow. 

sinh(), cosh() and tanh() return NaN and set errno to EDOM when x is NaN. 

These error-handling procedures can be changed by using the _matherr ( ) function (see jnatherr (3M)). 
Note that _matherr ( ) is provided in order to assist in migrating programs from libm.a to libM.a 
and is not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

isinf(3M), isnan(3M), matherr(3M). 

STANDARDS CONFORMANCE 

sinh () in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
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sinh ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, P0SIX.1, ANSI C 



cosh ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, P0SIX.1 
cosh ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

tanh ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
tanh ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

sleepO - suspend execution for interval 

SYNOPSIS 

ttinclude <unistd.h> 

unsigned int sleep (unsigned int seconds); 

DESCRIPTION 

sleep ( ) suspends the current process from execution for the number of seconds specified by the argu- 
ment. 

Actual suspension time can be less than that requested for two reasons: 

• Scheduled wakeups occur at fixed 1-second intervals (on the second, according to an internal clock), 
and 

• Any caught signal terminates the sleep following execution of that signal's catching routine. 

Suspension time can be an arbitrary amount longer than requested due to the scheduling of other activity 
in the system. The value returned by sleep ( ) is the "unslept" amount (the requested time minus the 
time actually slept) in case the caller had an alarm set to go off earlier than the end of the requested 
sleep ( ) time, or premature arousal due to another caught signal. 

sleep ( ) is implemented by setting an alarm signal and pausing until it (or some other signal) occurs. 
The previous state of the alarm signal is saved and restored. The calling program may have set up an 
alarm signal before calling sleep ( ) . If the sleep ( ) time exceeds the time until such an alarm signal, 
the process sleeps only until the alarm signal would have occurred. The caller's alarm catch routine is exe- 
cuted just before the sleep ( ) routine returns. If the sleep ( ) time is less than the time till such 
alarm, the prior alarm time is reset to go off at the same time it would have without the intervening 
sleep (). 

seconds must be less than 2 2 . 

SEE ALSO 

alarm(2), pause(2), signal(5). 

STANDARDS CONFORMANCE 

sleep ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

spray - scatter data in order to check the network 

SYNOPSIS 

#include <time.h> 
#include <rpcsvc/spray.h> 

DESCRIPTION 

This reference page describes the data structures and XDR routines used by the spray (1M) program. A 
spray ( ) function call does not exist. Refer to spray (1M) for more information. 

RPC Info 

program number: 

SPRAYPROG 

xdr routines: 

xdr_sprayarr(xdrs, arr); 

XDR *xdrs; 

struct sprayarr *arr; 
xdr_spraycumul(xdrs, cumul); 

XDR *xdrs; 

struct spraycumul *cumul; 
procs: 

SPRAYPROCJSPRAY 

Takes no arguments, returns no value. 

Increments a counter in server daemon. 

The server does not return this call, 

so the caller should have a timeout of 0. 

The sprayarr is only used by the caller, 

to vary the size of the UDP packets sent. 
SPRAYPROC_GET 

Takes no arguments, returns struct spraycumul 

with the values of counter and clock set to 

reflect the number of SPRAYPROC.SPRAY calls, 

and the total time (seconds and microseconds) 

elapsed since the last SPRAYPROC_CLEAR request. 
SPRAYPROC_CLEAR 

Takes no arguments and returns no value. 

Zeros out counter and clock in preparation 

for calls to SPRAYPROC.SPRAY. 
versions: 

SPRAYVERS.ORIG 

structures: 

struct spraycumul { 

unsigned counter; 
struct timeval clock; 

}; 

struct sprayarr { 
int *data; 
int lnth; 

}; 

WARNING 

User applications that call this routine must be linked with /usr/include/librpcsvc . a. For exam- 
ple, 

cc my_source.c -lrpcsvc 

AUTHOR 

spray was developed by Sun Microsystems, Inc. 

SEE ALSO 

spray(lM), sprayd(lM). 
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INTERNATIONAL SUPPORT 

8-bit data, 16-bit data, messages 



I 
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NAME 

sputl(), sgetl() - access long integer data in a machine-independent fashion 

SYNOPSIS 

#include <unistd.h> 

void sputldong int value, char *buf fer) ; 

DESCRIPTION 

sput 1 ( ) Take the four bytes of the long integer value and place them in memory starting at the 

address pointed to by buffer. The ordering of the bytes is the same across all machines. 

sgetl ( ) Retrieve the four bytes in memory starting at the address pointed to by buffer and return 

the long integer value in the byte ordering of the host machine. 

The combination of sputl() and sgetl () provides a machine-independent way of storing long 
numeric data in a file in binary form without conversion to characters. 

Any program that uses these functions must be loaded with the object-file access-routine library 1 Ibid. a. 

STANDARDS CONFORMANCE 

sputl():SVID2 

sgetl():SVID2 
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NAME 

ssignal( ), gsignal( ) - software signals 

SYNOPSIS 

ttinclude <signal.h> 

int (* ssignal (int sig, int (*action) (int) ) ) (int) ; 
int gsignal(int sig); 

DESCRIPTION 

ssignal ( ) and gsignal ( ) implement a software facility similar to signal(5). This facility is used by 
the Standard C Library to enable users to indicate the disposition of error conditions, and is also made 
available to users for their own purposes. 

Software signals made available to users are associated with integers in the inclusive range 1 through 15. 
A call to ssignal ( ) associates a procedure, action, with the software signal sig; the software signal, sig, 
is raised by a call to gsignal ( ) . Raising a software signal causes the action established for that signal to 
be taken. 

The first argument to ssignal ( ) is a number identifying the type of signal for which an action is to be 
established. The second argument defines the action; it is either the name of a (user-defined) action func- 
tionor one of the manifest constants S I G_DPL (default) or S I G_IGN (ignore), ssignal () returns the 
action previously established for that signal type; if no action has been established or the signal number is 
illegal, ssignal () returns SIG_DPL. 

gs ignal ( ) raises the signal identified by its argument, sig: 

• If an action function has been established for sig, that action is reset to SIGJDFL and the action 
function is entered with argument sig. gsignal () returns the value returned to it by the 
action function. 

• If the action for sig is SIG_IGN, gsignal ( ) returns the value 1 and takes no other action. 

• If the action for sig is SIG_DFL, gsignal ( ) returns the value and takes no other action. 

• If sig has an illegal value or no action was ever specified for sig, gsignal ( ) returns the value 
and takes no other action. 

SEE ALSO 

J(5). 



NOTES 

Some additional signals with numbers outside the range 1 through 15 are used by the Standard C Library 
to indicate error conditions. Those signal numbers outside the range 1 through 15 are legal, although their 
use may interfere with the operation of the Standard C Library. 

STANDARDS CONFORMANCE 

ssignal ( ) : SVID2, XPG2 

gs ignal ( ) : SVID2, XPG2 



HP-UX Release 9.0: August 1992 - 1 - 763 



long 


f_bavall 


/* 


long 


f_bf ree 


/* 


long 


f_b locks 


/* 


long 


f_bsize 


/* 


long 


f ffree 


/* 


long 


f_flles 


./* 


long 


f type 


/* 


fsid_ 


t f_fsld 


/* 



statfsdev(3C) statfsdev(3C) 



NAME 

statfsdev, fstatfsdev - get file system statistics 

SYNOPSIS 

# Include <sys/vfs.h> 

int statfsdev (const char *path, struct statfs *buf); 
lnt fstatfsdev (int fildes, struct statfs *buf); 

DESCRIPTION 

statfsdev ( ) returns information about the file system on the file specified by path. 

buf is a pointer to a statfs structure into which information is placed concerning the file system. The 
contents of the structure pointed to by buf include the following members: 

free blocks available to non-superuser */ 

free blocks */ 

total blocks in file system */ 

fundamental file system block size in bytes */ 

free file nodes in file system */ 

total file nodes in file system */ 

type of info, zero for now */ 

file system ID. f_fsid[l] is MOUNT_UFS, 

MOUNT_NFS, or MOUNT_CDFS */ 

Fields that are undefined for a particular file system are set to -1 . 

fstatfsdev ( ) returns the same information as above, but about the open file referred to by file descrip- 
tor fildes. 

RETURN VALUE 

Upon successful completion, statfsdev () and fstatfsdev () return zero. Otherwise, they return -1 
and set the global variable errno to indicate the error. 

ERRORS 

statfsdev ( ) fails if one or more of the following conditions are encountered: 

[EACCES] Search permission is denied for a component of the path prefix. 

[EAGAIN] The file exists, enforcement mode file/record locking is set, and there are outstanding 

record locks on the file. 

[EFAULT] path points to an invalid address. 

[ELOOP] Too many symbolic links are encountered in translating the path name. 

[EMFILE] The maximum number of file descriptors allowed are currently open. 

[ENAMETOOLONG] 

The length of the specified path name exceeds PATH_MAX bytes, or the length of a 
component of the pathname exceeds NAME_MAX bytes while _POSIX_NO_TRUNC 
is in effect. 

[ENFILE] The system file table is full. 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] The device specified by the named special file does not exist, 

fstatfsdev ( ) fails if one or more of the following is true: 

[EBADF] fildes is not a valid open file descriptor. 

[ESPIPE] filedes points to an invalid address. 

Both fstatfsdev () and statfsdev() fail if one or more of the following is true: 

[EAGAIN] Enforcement-mode record locking was set, and there was a blocking write lock. 
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[EDEADLK] A resource deadlock would occur as a result of this operation. 

[EINTR] A system call was interrupted by a signal. 

[EINVAL] The file specified by path or filedes does not contain a file system of any known type. 

[ENOLOCK] The system lock table was full, so the read could not go to sleep until the blocking 
write lock was removed. 

AUTHOR 

statf sdev ( ) and f statf sdev ( ) were developed by HP. 

FILES 

/usr/include/sys /mount .h 

SEE ALSO 

bdf(lM), df(lM), stat(2), statfs(2). 
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NAME 

stdio() - standard buffered input/output stream file package 

SYNOPSIS 

#lnclude <stdio.h> 

DESCRIPTION 

The Standard I/O functions described in the subsection (3S) entries of this manual constitute an efficient, 
user-level I/O buffering scheme. The getc ( ) and putc ( ) functions handle characters quickly. The fol- 
lowing funtions all use or act as if they use getc ( ) and putc ( ) , and can be freely intermixed: 

f get c ( ) f put s ( ) get char ( ) put char ( ) 

fgets() fread() gets() puts() 

fprintfO fscanfO getw() putw() 

f putc ( ) fwrite ( ) printf ( ) scanf ( ) 

A file with associated buffering is called a stream and is declared to be a pointer to a defined type FILE, 
f open ( ) creates certain descriptive data for a stream and returns a pointer to designate the stream in all 
further transactions. Section (3S) library routines operate on this stream. 

At program startup, three streams, standard input, standard output, and standard error, are predefined 
and do not need to be explicitly opened. When opened, the standard input and standard output streams are 
fully buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard 
error output stream is by default unbuffered. These three streams have the following constant pointers 
declared in the <stdio .h> header file : 

s t d i n standard input file 
stdout standard output file 
stderr standard error file 

A constant, NULL, (0) designates a nonexistent pointer. 

An integer-constant, EOF, (-1) is returned upon end-of-file or error by most integer functions that deal with 
streams (see individual descriptions for details). 

An integer constant BUFSIZ specifies the size of the buffers used by the particular implementation (see 
setbuf (SS)). 

Any program that uses this package must include the header file of pertinent macro definitions as follows: 

#include <stdio.h> 

The functions and constants mentioned in subsection (3S) entries of this manual are declared in that header 
file and need no further declaration. 

A constant _NFILE defines the default maximum number of open files allowed per process. To increase 
the open file limit beyond this default value, see setrlimit(2). 

SEE ALSO 

close(2), lseek(2), open(2), pipe(2), read(2), setrlimit(2), write(2), ctermid(3S), cuserid(3S), fclose(3S), 
ferror(3S), fgetpos(3S), fileno(3S), fopen(3S), fread(3S), fseek(3S), fsetpos(3S), getc(3S), gets(3S), popen(3S), 
printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), tmpfile(3S), tmpnam(3S), ungetc(3S). 

ERRORS 

Invalid stream pointers usually cause grave disorder, possibly including program termination. Individual 
function descriptions describe the possible error conditions. 

STANDARDS CONFORMANCE 

stderr: AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

st din: AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 
stdout: AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

ftok() - standard interprocess communication package 

SYNOPSIS 

#include <sys/ipc.h> 

key_t ftok (const char *path, int id); 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be used by the msgget ( ) , 
semget ( ) , and shmget ( ) system calls to obtain interprocess communication identifiers (see msgget(2), 
semgei(2), and shmget(2)). One suggested method for forming a key is to use the ftok() routine 
described below. Another way to compose keys is to include the project ID in the most significant byte, and 
use the remaining portion as a sequence number. There are many other ways to form keys, but it is neces- 
sary for each system to define standards for forming them. If some standard is not adhered to, it will be 
possible for unrelated processes to unintentionally interfere with each other's operation. Therefore, it is 
strongly suggested that the most significant byte of a key in some sense refer to a project so that keys do not 
conflict across a given system. 

ftok ( ) returns a key based on path and id that is usable in subsequent msgget ( ) , semget ( ) , and 
shmget ( ) system calls, path must be the path name of an existing file that is accessible to the process, id 
is a character that uniquely identifies a project. Note that f tok( ) returns the same key for linked files 
when called with the same id and that it returns different keys when called with the same file name but 
different ids. 

RETURN VALUE 

ftok ( ) returns (key_t) - 1 if path does not exist or if it is not accessible to the process. 

EXAMPLES 

The following call to f tok() returns a key associated with the file my file and id k: 

key_t my key; 

mykey = ftok ("myfile", 'A'); 

WARNINGS 

If the file whose path is passed to ftok() is removed when keys still refer to the file, future calls to 
ftok ( ) with the same path and id will return an error. If the same file is recreated, ftok ( ) is likely to 
return a different key than it did the original time it was called. 

In an HP Clustered environment, ftok ( ) can return a different key (using the same file name) when exe- 
cuted on different members of the cluster if any component of the file path name is a context-dependent file. 

SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2), cdf(4). 
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NAME 

strftime() - convert date and time to string 

SYNOPSIS 

#include <time.h> 

size_t strftime( 

nY» o m ft cr 
"""■'■ »» / 

size_t maxsize, 
const char ♦format, 
const struct tm *timeptr 
); 

DESCRIPTION 

strf time ( ) converts the contents of a tm structure (see ctime(3C)) to a formatted date and time string. 

strf time ( ) places characters into the array pointed to by s as controlled by the string pointed to by for- 
mat. The format string consists of zero or more directives and ordinary characters. A directive consists of a 
% character, an optional field width and precision specification, and a terminating character that deter- 
mines the directive's behavior. All ordinary characters (including the terminating null character are copied 
unchanged into the array. No more than maxsize characters are placed into the array. Each directive is 
replaced by the appropriate characters as described in the following list. The appropriate characters are 
determined by the program's locale, by the values contained in the structure pointed to by timeptr, and by 
the TZ environment variable (see External Influences below). 

Directives 

The following directives, shown without the optional field width and precision specification, are replaced by 
the indicated characters: 

%a Locale's abbreviated weekday name. 

%k Locale's full weekday name. 

Ssb Locale's abbreviated month name. 

%B Locale's full month name. 

%c Locale's appropriate date and time representation. 

Ssd Day of the month as a decimal number [01,31]. 

%E Locale's combined Emperor/Era name and year. 

%H Hour (24-hour clock) as a decimal number [00,23]. 

%I Hour (12 -hour clock) as a decimal number [01,12]. 

% j Day of the year as a decimal number [001,366]. 

%m Month as a decimal number [01,12]. 

%M Minute as a decimal number [00,59]. 

%n New-line character. 

%N Locale's Emperor/Era name. 

%o Locale's Emperor/Era year. 

%p Locale's equivalent of either AM or PM. 

%3 Second as a decimal number [00,61]. 

%t Tab character. 

%U Week number of the year (Sunday as the first day of the week) as a decimal number 

[00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. 
%w Weekday as a decimal number [0(Sunday),6]. 

%W Week number of the year (Monday as the first day of the week) as a decimal number 

[00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. 
%x. Locale's appropriate date representation. 

%X Locale's appropriate time representation. 

%y Year without century as a decimal number [00,99]. 

%Y Year with century as a decimal number. 

%Z Time zone name (or by no characters if no time zone exists). 
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The following directives are provided for backward compatibility with the directives supported by date(l) 
and the ctime(3C) functions. It is recommended that the directives above be used in preference to those 
below. 

%B Date in usual U.S. format (%m/%d/%y) (use %x instead). 

%F Locale's full month name (use %B instead). 

%h Locale's abbreviated month name (use %b instead). 

%r Time in 12-hour U.S. format (%I:%M:%S [AM | PM]) (use %X instead). 

%T Time in 24-hour U.S. format (%H:%M:%S) (use %X instead). 

%z Time zone name (or by no characters if no time zone exists) (use %Z instead). 

If a directive is not one of the above, the behavior is undefined. 

Field Width and Precision 

An optional field width and precision specification can immediately follow the initial % of a directive in the 
following order: 

[ - I 0]w the decimal digit string w specifies a minimum field width in which the result of the conver- 

sion is right- or left-justified. It is right-justified (with space padding) by default. If the 
optional flag '-' is specified, it is left-justified with space padding on the right. If the 
optional flag '0' is specified, it is right-justified and padded with zeros on the left. 

.p the decimal digit string/? specifies the minimum number of digits to appear for the d, H, I, 

j , m, M, o, S, U, w, W, y and Y directives, and the maximum number of characters to be 
used from the a, A, b, B, c, D, E, P, h, n, N, p, r, t, T, x, X, z, Z, and % directives. In the 
first case, if a directive supplies fewer digits than specified by the precision, it will be 
expanded with leading zeros. In the second case, if a directive supplies more characters 
than specified by the precision, excess characters will truncated on the right. 

If no field width or precision is specified for a d, H, I, m, M, S, U, W, y, or j directive, a default of . 2 is used 
for all but j for which . 3 is used. 

EXTERNAL INFLUENCES 
Locale 

The LC_TIME category determines the characters to be substituted for those directives described above as 
being from the locale. 

The LC_CTYPE category determines the interpretation of the bytes within format as single and/or multi- 
byte characters. 

The LC_NUMERIC category determines the characters used to form numbers for those directives that pro- 
duce numbers in the output. If ALT_DIGITS (see langinfo(5)) is defined for the locale, the characters so 
specified are used in place of the default ASCII characters. 

Environment Variables 

TZ determines the time zone name substituted for the %Z and %z directives. The time zone name is 
determined by calling the function tzset() which sets the external variable tzname (see ctime(SC)). 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If the total number of resulting characters including the terminating null character is not more than max- 
size, st rf time ( ) returns the number of characters placed into the array pointed to by s, not including 
the terminating null character. Otherwise, zero is returned and the contents of the array are indeter- 
minate. 

EXAMPLES 

If the timeptr argument contains the following values: 

timeptr— »tm_sec = 4; 
timeptr->tm_min = 9; 
timeptr-»tm_hour = 15; 
timeptr— >tm_mday = 4; 
timeptr— >tm_mon = 6; 
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timeptr-»tm_year = 88; 
timeptr-»tm_wday = 1; 
timeptr-»tm_yday = 185; 
timeptr->tm_isdst = 1; 

the following combinations of the LC_TIME category and format strings produce the indicated output: 



t r* fPTA/r-p 

JJV^_XJ.iT±Jil 


lOiinai; Sbiiug 


Output 


american 


%x 


Mon, Jul 4, 1988 


german 


%x 


Mo., 4. Juli 1988 


american 


%x 


03:09:04 PM 


french 


%X 


15h09 04 




%H:%M:%S 


15:09:04 


owyt 


%.1H:%.1M:%.1S 


15:9:4 


any\ 


%2.1H:%-3M:%03.1S 


15:9 :004 



t The directives used in these examples are not affected by the LC_TIME category of the locale. 

WARNINGS 

If the arguments s and format are defined such that they overlap, the behavior is undefined. 

The function tzset ( ) is called upon every invocation of strf time ( ) (whether or not the time zone 
name is copied to the output array). 

The range of values for %S ([0,61]) extends to 61 to allow for the occasional one or two leap seconds. How- 
ever, the system does not accumulate leap seconds and the tm structure generated by the functions 
localtime ( ) and gmtimeO (see ctime(3C)) never reflects any leap seconds. 

Results are undefined if values contained in the structure pointed to by timeptr exceed the ranges defined 
for the tm structure (see ctime(3C)) or are not consistent (such as if the tm_yday element is set to 0, indi- 
cating the first day of January, while the tm_mon element is set to 11, indicating a day in December). 

AUTHOR 

strf time ( ) was developed by HP. 

SEE ALSO 

date(l), ctime(3C), getdate(3C), setlocale(3C), environ(5), langinfo(5), hpnls(5). 

STANDARDS CONFORMANCE 

strf time ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

strcat(), strncatQ, strcmpQ, stmcmpQ, strcasecmpO, strncasecmp( ), strcpyO, strncpyO, strdupQ, strlen(), 
strchrQ, strrchr(), strpbrk(), strspn(), strcspn(), strstr(), strrstrO, strtok(), strcolK), strxfrm(), nl_strcmp( ), 
nl_strncmp(), index(), rindex() - character string operations 

SYNOPSIS 

ttinclude <string.h> 
#include <strings.h> 

char *strcat(char *sl, const char *s2); 

char *strncat (char *sl, const char *s2, size_t n) ; 

int strcmp(const char *sl, const char *s2); 

int strncmp (const char *sl, const char *s2, size_t n) ; 

int strcasecmp (const char *sl / const char *s2); 

int st rncasecmp (const char *sl, const char *s2, size_t n) ; 

char *strcpy(char *sl, const char *s2); 

char *strncpy(char *sl, const char *s2, size_t n) ; 

char *strdup (const char *s); 

size_t strlen(const char *s) ; 

char *strchr (const char *s, int c) ; 

char *strrchr (const char *s, int c); 

char *strpbrk( const char *sl, const char *s2); 

size_t strspn(const char *sl, const char *s2); 

size_t strcspn(const char *sl, const char *s2); 

char *strstr (const char *sl, const char *s2); 

char *strrstr (const char *sl, const char *s2); 

char *strtok(char *sl, const char *s2); 

int strcoll (const char *sl, const char *s2); 

size_t strxf rm(char *sl, const char *s2, size_t n) ; 

int nl_strcmp( const char *sl, const char *s2); 

int nl_strncmp (const char *sl, const char *s2, size_t n) ; 

char *index(const char *s, int c); 

char *rindex(const char *s, int c) ; 

Remarks: 

All functions except index () and r index () are declared in both headers, so only one of the two 
headers needs to be included. 

The functions index ( ) and r index ( ) are declared only in <st rings .h>, They and <st rings .h> 
are provided solely for portability of BSD applications, and are not recommended for new applications where 
portability is important. For portable applications, use <string.h>, strchrO, and strrchrO 
instead. 

index ( ) and rindex ( ) and <strings .h> are provided solely for portability of BSD applications, and 
are not recommended for new applications where portability is important. For portable applications, use 
strchr() and strrchrO instead. 

DESCRIPTION 

Arguments sl,s2, and s point to strings (arrays of characters terminated by a null byte). 
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Definitions for all these functions, the type s ize_t, and the constant NULL are provided in the <stringJi> 
header. 



strcat () 



strcpy() 



strdup() 

strlen() 
strchr() 



strpbrk() 
strspn() 
strstr () 

strtok() 



strcoll() 



Appends a copy of string s2 to the end of string si . strncat ( ) appends a maximum of 
n characters. It copies fewer if s2 is shorter than n characters. Each returns a pointer to 
the null-terminated result (the value of si). 






strxfrm() 



depending on whether si is lexicographically less than, equal to, or greater than s2 . The 
comparison of corresponding characters is done as if the type of the characters were 
unsigned char. Null pointer values for si and s2 are treated the same as pointers to 
empty strings, strncmp ( ) makes the same comparison but examines a maximum of n 
characters (n less than or equal to zero yields equality). strcasecmp() and 
strncasscmp ( ) are identical in function to strcmpC) anu strncinp( ) respectively, 
but characters are folded by _tolower() (see conv{ZC)) prior to comparison. The 
returned lexicographic difference reflects the folding to lowercase. 

Copies string s2 to si, stopping after the null byte has been copied, strncpy ( ) copies 
exactly n characters, truncating s2 or adding null bytes to si if necessary, until a total of n 
have been written. The result is not null-terminated if the length of s2 is n or more. Each 
function returns si . Note that should not be used to copy n bytes of an arbitrary structure. 
If that structure contains a null byte anywhere, strncpy ( ) copies fewer than n bytes 
from the source to the destination and fills the remainder with null bytes. Use the 
memcpy ( ) function (see memory(SC)) to copy arbitrary binary data. 

Returns a pointer to a new string which is a duplicate of the string to which si points. The 
space for the new string is obtained using the malloc ( ) function (see malloc (3C)). 

Returns the number of characters in s, not including the terminating null byte. 

(strrchr ( ) ) Returns a pointer to the first (last) occurrence of character c in string s, or a 
null pointer if c does not occur in the string. The null byte terminating a string is con- 
sidered to be part of the string, index () (rlndexO) is identical to strchrO 
(strrchr ( ) ), and is provided solely for portability of BSD applications. 

Returns a pointer to the first occurrence in string si of any character from string s2, or a 
null pointer if no character from s2 exists in si . 

(strcspn ( ) ) Returns the length of the maximum initial segment of string si, which con- 
sists entirely of characters from (not from) string s2. 

(strrstr ( )) Returns a pointer to the first (last) occurrence of string s2 in string si, or a 
NULL pointer if s2 does not occur in the string. If s2 points to a string of zero length, 
strstr () (strrstr ())returns si. 

Considers the string si to consist of a sequence of zero or more text tokens separated by 
spans of one or more characters from the separator string s2 . The first call (with a non-null 
pointer si specified) returns a pointer to the first character of the first token, and writes a 
null byte into si immediately following the returned token. The function keeps track of its 
position in the string si between separate calls, so that subsequent calls made with the 
first argument a null pointer work through the string immediately following that token. In 
this way subsequent calls work through the string si until no tokens remain. The separa- 
tor string s2 can be different from call to call. When no token remains in si , a null pointer 
is returned. 

Returns an integer greater than, equal to, or less than zero, according to whether the string 
pointed to by si is greater than, equal to, or less than the string pointed to by s2. The com- 
parison is based on strings interpreted as appropriate to the program's locale (see Locale 
below). In the "C locale strcoll() works like strcmpC ) . nl_strcmp() is pro- 
vided for historical reasons only and is equivalent to strcoll ( ) . nl_strncmp ( ) , also 
provided only for historical reasons, makes the same comparisons as strcoll (), but 
looks at a maximum of n. characters (n less than or equal to zero yields equality). 

Transforms the string pointed to by s2 and places the resulting string into the array 
pointed to by si . The transformation is such that if the strcmp ( ) function is applied to 
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two transformed strings, it returns a value greater than, equal to, or less than zero, 
corresponding to the result of the strcoll ( ) function applied to the same two original 
strings. No more than n bytes are placed into the resulting string, including the terminat- 
ing null character. If the transformed string fits in no more than n bytes, the length of the 
resulting string is returned (not including the terminating null character). Otherwise the 
return value is the number of bytes that the si string would occupy (not including the ter- 
minating null character), and the contents of the array are indeterminate. 

strcoll ( ) has better performance with respect to strxf rm( ) in cases where a given string is com- 
pared to other strings only a few times, or where the strings to be compared are long but a difference in the 
strings that determines their relative ordering usually comes among the first few characters, 
strxf rm( ) offers better performance in, for example, a sorting routine where a number of strings are 
each transformed just once and the transformed versions are compared against each other many times. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the interpretation of the bytes within the string arguments to the 
strcoll ( ) , strxf rm( ) , nl_strcmp ( ) , and nl_strncmp ( ) functions as single and/or multi-byte 
characters. It also determines the case conversions to be done for the strcasecmp() and 
strncasecmp ( ) functions. 

The LC_COLLATE category determines the collation ordering used by the strcoll (), strxfrm(), 
nl_strcmp( ), and nl_stmcmp () functions. See hpnls(S) for a description of supported collation 
features. Use nlsinf o (see nlsinfo(Vj) to view the collation used for a particular locale. 

International Code Set Support 

Single- and multi-byte character code sets are supported for the strcoll (), strxfrm(), 
nl_strcmp( ), and nl_strncmp( ) functions. All other functions support only single-byte character 
code sets. 

WARNINGS 

The functions st rcat ( ) , st meat ( ) , strcpy ( ) , st rncpy ( ) , and strtok ( ) alter the contents of 
the array to which si points. They do not check for overflow of the array. 

Null pointers for destination strings cause undefined behavior. 

Character movement is performed differently in different implementations, so moves involving overlapping 
source and destination strings may yield surprises. 

The transformed string produced by strxf rm( ) for a language using an 8-bit code set is usually at least 
twice as large as the original string and may be as much four times as large (ordinary characters occupy 
two bytes each in the transformed string, l-to-2 characters four bytes, 2-to-l characters two bytes per origi- 
nal pair, and don't-care characters no bytes). Each character of a multi-byte code set (Asian languages) 
occupies three bytes in the transformed string. 

For functions strcoll ( ) , strxf rm ( ) , nl_strcmp ( ) , and nl_st rnemp ( ) , results are undefined if 
the languages specified by the LC_COLLATE and LC_CTYPE categories use different code sets. 

AUTHOR 

string was developed by AT&T, HP, and the University of California, Berkeley. 

SEE ALSO 

nlsmfo(l), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). 

STANDARDS CONFORMANCE 

nl_strcmp ( ) : XPG2 
nl_strncmp ( ) : XPG2 

S treat ( ) : AES, SVID2, XPG2,XPG3,XPG4,FIPS 151-2, POSK.1, ANSI c 

s t rchr ( ) : aes, svtd2, xpg2, xpg3, XPG4, fips 151-2, poseci, ansi c 

S t remp ( ) : AES, SVID2, XPG2, XPG3, XPG4, PIPS 151-2, POSIX.1, ANSI c 

strcoll(): aes, xpg3, xpg4, ansi c 

St rcpy ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI c 
S t re Spn ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI c 
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strdup(): sviD2 

s t r len ( ) : aes, sviD2, xpg2, xpg3, xpg4, fips 151-2, posdci, ansi c 

st rncat ( ) : aes, svid2, xpg2, xpg3, xpg4, fips 151-2, posdci, ansi c 
st rncmp ( ) : aes, svid2, xpg2, xpg3, xpg4, pips 151-2, posdci, ansi c 

st rncpy ( ) : aes, svid2, xpg2, xpg3, xpg4, fips 151-2, posdci, ansi c 
st rpbrk. ( } : aes, sviD2, xpgz, xpgs, xpg4, fips 151-2, posdci, ansi c 

st rrchr ( ) : aes, svtd2, xpg2, xpg3, xpg4, fips 151-2, posdci, ansi c 

S t r Spn ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSDCI, ANSI c 

Strstr ( ) : AES, XPG3, XPG4, FIPS 151-2, POSDCI, ANSI C 

S t rt Ok ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSDCI, ANSI c 

st rxf rm ( ) : aes, xpg3, xpg4, ansi c 
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NAME 

strord - convert string data order 

SYNOPSIS 

#include <nl_types.h> 

char *strord(char *sl, const char *s2, nl_mode m) ; 

DESCRIPTION 

The text orientation (mode) of a file can be right-to-left (non-Latin) or left-to-right (Latin). This text orien- 
tation can affect the way data is arranged in the file. The data arrangements that result are called screen 
order and keyboard order (see hpnls(5) for more details). 

strord ( ) converts the order of characters in s2 from screen to keyboard order or vice versa and places the 
result in si . The arguments si and s2 point to strings (arrays of characters terminated by a null charac- 
ter), strord () returns si. 

strord ( ) performs the conversion based on mode information indicated by the argument m. The argu- 
ment m is of type nl_mode found in the header file <nl_types .h>. The mode argument can have two 
possible values: NL_LAT IN and NL_NONLAT IN. 

If the mode argument is NL_LATIN, the text orientation is left-to-right, and all non-Latin sub-strings are 
reversed. Non-Latin sub-strings are any number of contiguous right-to-left language characters. Non- 
Latin sub-strings are delimited by ASCII characters. 

Similarly, if the mode argument is NL_NONLATIN, the text orientation is right-to-left and all Latin sub- 
strings are reversed. Latin sub-strings are any number of contiguous printable ASCII characters. Latin 
sub-strings are delimited by right-to-left language characters and ASCII control codes. 

Some right-to-left languages have a duplicate set of digits called alternative numbers. Alternative numbers 
always have a left-to-right orientation. 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category determines whether a right-to-left language has alternative numbers. 

International Code Set Support 

Single-byte character code sets are supported. 

WARNINGS 

strord ( ) does not check for overflow of the array pointed to by si . 

AUTHOR 

strord ( ) was developed by HP. 

SEE ALSO 

nl_init(3C), hpnls(5), environ(5), forder(l), nljust(l). 
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NAME 

strtoacl(), strtoaclpatt(), aclentrystart() - convert exact or pattern string form to access control list (ACL) 
structure 

SYNOPSIS 

#include <acllib.h> 

int strtoacl ( 

const char ♦string, 

int nentries, 

int maxentries, 

struct acl_entry *acl, 

int fuid, 

int fgid 
); 

int strtoaclpatt ( 

const char *string, 

int maxentries, 

struct acl_entry_patt *acl 
); 

DESCRIPTION 

strtoacl ( ) converts an access control list from exact symbolic (string) representation to structure form. 
It parses the input string and verifies its validity. Optionally it applies the entries in the string as a series 
of changes to an existing ACL. 

strtoaclpatt ( ) converts an access control list pattern from symbolic (string) representation to struc- 
ture form. It parses the input string and verifies its validity. 

The external array aclentrystart [ ] , only valid until the next call of either routine, is useful for error 
reporting. See ERRORS below. 

The "operator" and "short" symbolic forms of ACLs and ACL patterns (described in acl(5)) are acceptable as 
input strings. If the first non-whitespace character in string is (, the ACL or ACL pattern in string must be 
in short form. Otherwise operator form is assumed. 

strtoacl ( ) takes a pointer to the string to be converted, and a pointer to the first element of an array of 
ACL entries (acl []) initially containing the indicated number {nentries) of valid entries (zero or more). 
This array can grow to the indicated number of entries (maxentries). strtoacl ( ) also takes file user ID 
(fuid) and group ID (fgid) values to substitute for @ characters in string and returns the resulting number 
of entries in ac 1 [ ] . 

Redundant entries (identical user ID and group ID values after processing @ characters) are combined, so 
that acl [ ] contains unique entries in the order encountered. If a new entry is mentioned, it is added to 
the end of the acl array. 

strtoaclpatt () 

strtoaclpatt () differs from strtoacl () because it processes an ACL pattern instead of an ACL. 
Since modification of an existing initial ACL is not useful, it is not supported. 

Entries with matching user and group ID values are not combined. Each entry input yields one entry in the 
returned array. 

The @ character for user and group IDs (see acl(5)) is converted to special values (ACL_PILEOWNER or 
ACL_PILEGROUP, respectively, defined in <acllib . h>), not to specific user or group names provided by 
the caller. Thus, strtoaclpatt ( ) need not be called to reparse the ACL pattern for each file, but the 
caller must handle the special values when comparing an ACL pattern to an ACL. 

Wildcard user names, group names, and mode values are supported, as are absent mode parts; see acl(5). 

strtoaclpatt ( ) returns a different structure than strtoacl ( ) . The acljentry_patt structure con- 
tains onmode and off mode masks rather than a single mode value. 

In operator form input, operators have a different effect on strtoaclpatt ( ) : 



776 - 1 - HP-UX Release 9.0: August 1992 



strtoacl (3C) strtoacl(3C) 



= Sets bits in both the onmode and offmode fields appropriately, replacing existing bits in the 
entry, including any set by earlier operators. 

+ Sets bits in onmode and clears the same bits in offmode. 

Sets bits in offmode and clears the same bits in onmode. 

In short form input, the mode is treated like the = operator in operator form. 

For both routines, a non-specific user or group ID of % is converted to ACL_NSUSER or ACL_NSGROUP, 
respectively. For strtoaclpatt ( ) only, a wildcard user or group ID of * is converted to 
ACL_ANYUSER or ACL_ANYGROUP, respectively. The values are defined in <acllib .h>. 

Entries can appear in string in any order, string can contain redundant entries, and in operator form 
only, redundant + and - operators for ACL entry mode modifications (in exact form) or mode bit 
inclusions/exclusions (in patterns). Entries or modifications are applied left to right. 

Suggested Use 

To build a new ACL (ACL pattern) array using strtoacl ( ) (strtoaclpatt ( ) ), define acl [ ] with as 
many entries as desired. Pass it to strtoacl () (strtoaclpatt ( )) with nentries set to zero 
(strtoacl ( ) only) and maxentries set to the number of elements in acl [ ] . 

To have strtoacl ( ) modify a file's existing ACL, define acl [ ] with the maximum possible number of 
entries (NACLENTRIES; see <sys/acl .h>). Call getacl ( ) (see getacl(2)) to read the file's ACL and 
stat ( ) (see stat(2)) to get the file's owner and group IDs. Then pass the current number of entries, the 
current ACL, and the ID values to strtoacl ( ) with maxentries set to NACLENTRIES. 

If strtoacl () succeeds, the resulting ACL can be passed safely to setacl() (see setacl (2)) because all 
redundancies (if any) have been resolved. However, note that since neither strtoacl ( ) nor 
strtoaclpatt () validate user and group ID values, if the values are not acceptable to the system, 
setacl ( ) fails. 

Performance Trick 

Normally strtoacl ( ) replaces user and group names of & with specific user and group ID values, and 
also combines redundant entries. Therefore, calling stat ( ) and strtoacl ( ) for each of a series of 
files to which an ACL is being applied is simplest, although time consuming. 

If string contains no & character, or if the caller merely wants to compare one ACL against another (and 
will handle the special case itself), it is sufficient to call strtoacl ( ) once, and pointless to call stat ( ) 
for each file. To determine this, call strtoacl ( ) the first time with fuid set to ACL_FILEOWNER and 
fgid set to ACLJFILEGROUP. Repeated calls with file-specific fuid and fgid values are needed only if the 
special values of fuid and fgid appear in acl [ ] and the caller needs an exact ACL to set on each file; see 
EXAMPLES below. 

If @ appears in string and acl [] will be used later for a call to setacl ( ), it is necessary to call 
strtoacl ( ) again to reparse the ACL string for each file. It is possible that not all redundant entries 
were combined the first time because the @ names were not resolved to specific IDs. This also complicates 
comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator 
information from operator form input might be lost. 

RETURN VALUE 

If strtoacl () (strtoaclpatt ()) succeeds, it returns the number of entries in the resulting ACL 
(ACL pattern), always equal to or greater than nentries (zero). 

strtoaclpatt ( ) also sets values in global array aclentrystart [ ] to point to the start of each pat- 
tern entry it parsed in string, in some cases including leading or trailing whitespace. It only sets a number 
of pointers equal to its return value plus one (never more than NACLENTRIES + 1). The last valid ele- 
ment points to the null character at the end of string. After calling strtoaclpatt ( ) , an entry pattern's 
corresponding input string can be used by the caller for error reporting by (temporarily) putting a null at 
the start of the next entry pattern in string. 

ERRORS 

If an error occurs, strtoacl () and strtoaclpatt ( ) return a negative value and the content of 
acl is undefined (was probably altered). To help with error reporting in this case, aclentrystart [ ] 
and aclentrystart [1 ] are set to point to the start of the current and next entries, respectively, being 
parsed when the error occurred. If the current entry does not start with (, aclentrystart [1] points 
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to the next null character or comma at or after aclentrystart [0] . Otherwise, it points to the next 
null, or to the character following the next ) . 

The following values are returned in case of error: 

-1 Syntax error: entry doesn't start with ( as expected in short form. 

-2 Syntax error: entry doesn't end with ) as expected in short form. 

-3 Syntax error: user name is not terminated by a dot. 

-4 (strtoacl () only) Syntax error: group name is not terminated by an operator in operator- 
form input or a comma in short-form input. 

-5 Syntax error: user name is null. 

-6 Syntax error: group name is null. 

-7 Invalid user name (not found in /etc/passwd file and not a valid number). 

-8 Invalid group name (not found in /etc /group file and not a valid number). 

-9 Syntax error: invalid mode character, other than 0.. 7, r, w, x, - (allowed in short form only), * 
(allowed in patterns only), , (to end an entry in operator form), or ) (to end an entry in short 
form). Or, 0..7 or * is followed by other mode characters. 

-10 The resulting ACL would have more than maxentries entries. 

EXAMPLES 

The following code fragment converts an ACL from a string to an array of entries using an fu id of 103 for the 
file's owner and fgid of 45 for the file's group. 

#include <acllib.h> 

int nentries; 

struct acl_entry acl [NACLENTRIES] ; 

if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0) 
error (...); 

The following code gets the ACL, fuid, and fgid for file . . /myf ile, modifies the ACL using a description 
string, and changes the ACL on file . . /myf i le2 to be the new version. 

ttinclude < sys/ types. h> 
#include <sys/stat.h> 
#include <acllib.h> 

struct stat statbuf; 

int nentries; 

struct acl_entry acl [NACLENTRIES] ; 

if (stat (". ./myf ile", & statbuf) < 0) 
error (...); 

if ((nentries = getacl ( " . ./myf ile", NACLENTRIES, acl)) < 0) 
error (...); 

if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl, 

statbuf .st_uid, statbuf .st_gid) ) < 0) 
{ 

error (...); 
} 

if (setacl ( " . ./myf ile2", nentries, acl) < 0) 
error (...); 

The following code fragment calls strtoacl ( ) with special values of fuid and fgid, then checks to see if 
they show up in acl [ ] . 

ttinclude <acllib.h> 
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int perfile =0; /* need to stat() and reparse per file? */ 
int entry; 

if ( (nentries = strtoacl (string, 0, NACLENTRIES, acl, 

ACL_FILEOWNER, ACL_FILEGROUP ) ) < 0) 
{ 

error (...)/ 
} 

for (entry = 0; entry < nentries; entry++) 
{ 

if ((acl [entry] . uid == ACL_FILEOWNER) 

II (acl [entry] . gid == ACL_FILEGROUP) ) 
{ 

perfile = 1; 
break; 
} 
} 

The following code fragment converts an ACL pattern from a string to an array of pattern entries. 

#include <acllib.h> 

int nentries; 

struct acl_entry_patt acl [NACLENTRIES] ; 

if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0) 
error (...); 

The following code fragment inside a for loop checks an entry pattern (p*, onmask, and of fmask vari- 
able names) against an entry in a file's ACL (a* variable names) using the file's user and group IDs (f * 
variable names). 

include <unistd.h> 

if (((puid == ACL_FILEOWNER) && (fuid != auid) ) 

II ((puid != ACL_ANYUSER) && (puid != auid))) 
{ 

continue; 
} 

if (((pgld == ACL_FILEGROUP) && (fgid != agid) ) 

II ((pgid != ACL_ANYGROUP ) && (pgid != agid))) 
{ 

cont inue ; 
} 

if (((( amode) & MODEMASK & onmask ) != onmask) 

II (((~ amode) & MODEMASK & of fmask) != of fmask) ) 
{ 

cont inue ; 
} 

AUTHOR 

strtoacl () and strtoaclpatt ( ) were developed by HP. 

FILES 

/etc/passwd 
/etc/group 

SEE ALSO 

getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5). 
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NAME 

strtod, atof, nl_strtod, nl_atof - convert string to double-precision number 

SYNOPSIS 

#include <stdlib.h> 

double strtod(const char *str, char **ptr) ; 

double atof (const char *str) ; 

double nl_strtod (const char *str, char **ptr, lnt langld) ; 

double nl_atof (const char *str, lnt langid) ; 

DESCRIPTION 

strtod () returns, as a double-precision floating-point number, the value represented by the character 
string pointed to by str. The string is scanned (leading white-space characters as defined by lsspace ( ) 
in ctype(3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is 
returned. 

strtod ( ) recognizes characters in the following sequence: 

1. An optional string of "white-space" characters which are ignored, 

2. An optional sign, 

3. A string of digits optionally containing a radix character, 

4. An optional e or E followed by an optional sign or space, followed by an integer. 

The radix character is determined by the loaded NLS environment (see setlocale(3C)). If set locale ( ) 
has not been called successfully, the default NLS environment, "C", is used (see lang(5)). The default 
environment specifies a period (.) as the radix character. 

If the value ofptr is not (char ** )NULL , the variable to which it points is set to point at the charac- 
ter after the last number, if any, that was recognized. If no number can be formed, *ptr is set to str, and 
zero is returned. 

atof {str ) is equivalent to strtod {str , ( char * * ) NULL ) . 

nl_strtod ( ) and nl_atof ( ) are similar to the above routines, but first call langlnlt ( ) (see 
nl_init(3C)) to load the NLS envirnnrnpnt specified by langid. 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category determines the value of the radix character within the currently loaded NLS 
environment. 

RETURN VALUE 

If the correct value would cause overflow, +HU6E_VAL or -HUGE_VAL is returned (according to the sign 
of the value), and errno is set to ERANGE. 

If the correct value would cause underflow, zero is returned and errno is set to ERANGE. 

WARNINGS 

nl_strtod ( ) and nl_atof ( ) are provided for historical reasons only. Their use is not recommended. 
Use strtodO and atof () instead. 

AUTHOR 

strtod ( ) was developed by AT&T and HP. 

SEE ALSO 

ctype(3C), setlocale(3C), scanf(3S), strtol(3C), hpnls(5), lang(5). 

STANDARDS CONFORMANCE 

strtod ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 

atof ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

strtol, atol, atoi, strtoul - convert string to integer 

SYNOPSIS 

#include <stdlib.h> 

long strtol (const char *str, char **ptr, int base); 

long atol (const char *str) ; 

int atol (const char *str); 

unsigned long strtoul (const char *str, char **ptr, int base); 

DESCRIPTION 

strtol () (strtoul ()) converts the character string pointed to by str to long int (unsigned 
long int) representation. The string is scanned up to the first character inconsistent with the base. 
Leading "white-space" characters (as defined by is space ( ) in ctype(SC)) are ignored. If no conversion 
can take place, zero is returned. 

If base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After 
an optional leading sign, leading zeros are ignored, and Ox or OX is ignored if base is 16. 

If base is zero, the string itself determines the base as follows: After an optional leading sign, a leading zero 
indicates octal conversion; a leading Ox or OX hexadecimal conversion. Otherwise, decimal conversion is 
used. 

If the value of ptr is not ( char * * ) NULL, a pointer to the character terminating the scan is returned in 
the location pointed to by ptr. If no integer can be formed, the location pointed to by ptr is set to str, and 
zero is returned. 

atolfstrj is equivalent to strtol {str, (char **)NULL / 10). 

atoi {str) is equivalent to int strtol {str, (char **)NULL, 10). 

RETURN VALUE 

Upon successful completion, all functions return the converted value, if any. If the correct value would 
cause overflow, strtol ( ) returns LONG_MAX or LONG_MIN (according to the sign of the value), and 
sets errnotoERANGE; strtoul () returns ULONG_MAX and sets errno to ERANGE. Overflow condi- 
tions are ignored by atol ( ) and atoi ( ) . 

For all other errors, zero is returned and errno is set to indicate the error. 

ERRORS 

strtol () and strtoul () fail and errno is set if any of the following conditions are encountered: 

[EINVAL] The value of base is not supported. 

[ERANGE] The value to be returned would have caused overflow. 

SEE ALSO 

ctype(3C), strtod(3C), scan#3S). 

STANDARDS CONFORMANCE 

strtol ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 

atoi ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
atol ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
strtoul ( ) : AES, XPG4, ANSI C 
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NAME 

strtold() - convert string to long double-precision number 

SYNOPSIS 

#include <stdlib.h> 

long_double strtold(const char *str, char **ptr) ; 

DESCRIPTION 

strtold() returns as a long double-precision number the value represented by the character string 
pointed to by str. The string is scanned up to the first unrecognized character. 

strtoldO recognizes an optional string of "white-space" characters (as defined by isspace() in 
ctype(3C)), then an optional sign, then a string of digits optionally containing a radix character, then an 
optional e or 1 followed by an optional sign or space, followed by an integer. The radix character is deter- 
mined by the loaded NLS environment (see nl_init(3C)). If nl_in.it ( ) has not been called successfully, 
the default NLS environment, "C" (see lang(5)), is used. The default environment specifies a period (.) as 
the radix character. 

If the value ofptr is not (char **)NULL, the variable to which it points is set to point at the character 
after the last number, if any, that was recognized. If no number can be formed, *ptr is set to str, and zero is 
returned. 

EXTERNAL INFLUENCES 

International Code Set Support 

Single-byte character code sets are supported. 

RETURN VALUE 

If the correct value would cause overflow, +_MAXLDBL or -_MAXLDBL is returned (according to the sign 
of the value), and errno is set to ERANGE. 

If the correct value would cause underflow, zero is returned and errno is set to ERANGE. 

AUTHOR 

st rtold ( ) was developed by HP. 

SEE ALSO 

ctype(3C), nl_init(3C), scanf(3S), hpnls(5), lang(5). 
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NAME 

swab( ) - swap bytes 

SYNOPSIS 

#include <unistd.h> 

void swab(const void *from, void *to, ssize_t nbytes); 

DESCRIPTION 

swab ( ) copies nbytes bytes pointed to by from to the array pointed to by to, exchanging adjacent even and 
odd bytes. It is useful for carrying binary data between byte-swapped and non-byte-swapped machines. 
nbytes should be even and non-negative. If nbytes is odd and positive swab() uses nbytes-1 instead. If 
nbytes is negative, swab ( ) does nothing. 

STANDARDS CONFORMANCE 

swab ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

syslog(), openlogO, closelogO, setlogmask() - control system log 

SYNOPSIS 

ftinclude <syslog.h> 

int syslog(int priority, const char *message, int parameters, ...); 

int openiog(const char *ident, int logopt, int facility); 

int closelog(void) ; 

int setlogmask(int maskpri); 

DESCRIPTION 

syslogf) writes a message onto the system log maintained by syslogd (see sysiogd(xM)j. The 
message is tagged with priority. The message is similar to a printf "(3S) format string except 
that Ssm is replaced by the error message associated with the current value of errno. A 
trailing newline is added if needed. 

This message is read by sys logd and written to the system console, log files, selected 
users' terminals, or forwarded to sys logd on another host as appropriate. 

priority is encoded as the logical OR of a level and a facility. The level signifies the urgency 
of the message, and facility signifies the subsystem generating the message, facility can be 
encoded explicitly in priority, or a default facility can be set with openlog ( ) (see below). 

level is selected from an ordered list: 



LOG_EMERG 
LOG ALERT 



LOG_CRIT 
LOG_ERR 
LOG_WARNING 
LOG_NOTICE 

LOG_INFO 
LOG DEBUG 



A panic condition. This is normally broadcast to all users. 

A condition that should be corrected immediately, such as a cor- 
rupted system database. 

Critical conditions, such as hard device errors. 

Errors. 

Warning messages. 

Conditions that are not error conditions, but should possibly be 
handled specially. 

Informational messages. 

Messages that contain information normally of use only when 
debugging a program. 

sys log ( ) does not log a message that does not have a level set. 

If syslog() cannot pass the message to syslogd, it attempts to write the message on 
/dev/console if the LOG_CONS option is set (see below). 

openlogO 

can be called to initialize the log file, if special processing is needed, ident is a string that precedes 
every message, logopt is a mask of bits, logically OR'ed together, indicating logging options. The 
values for logopt are: 

LOG_PID Log the process ID with each message; useful for identifying instantiations 

of daemons. 

LOG_CONS Force writing messages to the console if unable to send it to syslogd. 

This option is safe to use in daemon processes that have no controlling ter- 
minal because sys log ( ) forks before opening the console. 

LOG_NDELAY Open the connection to syslogd immediately. Normally, the open is 

delayed until the first message is logged. This is useful for programs that 
need to manage the order in which file descriptors are allocated. 

LOG_NOWAIT Do not wait for children forked to log messages on the console. This option 

should be used by processes that enable notification of child termination 
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via SIGCLD, because syslogO might otherwise block, waiting for a 
child whose exit status has already been collected. 

facility encodes a default facility to be assigned to all messages written subsequently by syslog ( ) 
with no explicit facility encoded. 

LOG_KERN Messages generated by the kernel. These cannot be generated by any user 

processes. 

LOG__USER Messages generated by random user processes. This is the default facility 

identifier if none is specified. 

LOG_MAIL The mail system. 

LOG_DAEMON System daemons, such as inetd(lM), ftpd(lM\ etc. 

LOG_AUTH The authorization system: login(l), su(l), gettyilM), etc. 

LOG_LPR The line printer spoofing system: lp(l), lpsched(lM\ etc. 

LOG_LOCAL0 Reserved for local use. Similarly for LOG_LOCALl through 

LOG_LOCAL7 . 

closelog( ) 
closes the log file. 

setlogmaskO 

sets the log priority mask to maskpri and returns the previous mask. Calls to syslog ( ) with a 
priority not set in maskpri are rejected. The mask for an individual priority pri is calculated by the 
macro LOG_MASK {pri ) ; the mask for all priorities up to and including toppri is given by the macro 
LOG_UPTO(toppriJ . By default, all priorities are logged. 

RETURN VALUE 

syslog () returns zero if it is successful in writing to the system log or if priority is masked out. It 
returns —1 if it is unable to write to the system log or if priority is out of range. 

EXAMPLES 

who logs a message regarding some sort of unexpected and serious error: 

syslog (LOG_ALERT, "who: Internal error 23");/s0 

f tpd uses openlog ( ) to arrange to log its process ID, to log to the console if necessary, and to log in the _ 

name of the daemon facility: I 

openlog ("f tpd", LOG_PID|LOG_CONS / LOG_DAEMON) ; 
Arrange to log messages only at levels LOG_ERR and lower: 

setlogmask(LOG_UPTO(LOGJERR) ) ; 
Typical usage of syslog ( ) to log a connection: 

syslog (LOG_INFO, "Connection from host %&" , CalllngHost) ; 
If the facility has not been set with openlog ( ) , it defaults to LOG_USER. 
Explicitly set the facility for this message: 

syslog (LOG_INFO|LOG_LOCAL2, "foobar error: %m") ; 

WARNINGS 

A call to syslog () has no effect unless the syslog daemon (syslogdi 1M)) is running, openlog () does 
not copy and store the ident string internally; it stores only a character pointer. Therefore it is the responsi- 
bility of the programmer to make sure that the ident argument points to the correct string until the log file 
is closed. 

AUTHOR 

syslog ( ) was developed by the University of California, Berkeley. 
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SEE ALSO 

logger(l), syslogd(lM). 
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NAME 

systemO - issue a shell command 

SYNOPSIS 

#include <stdlib.h> 

int system(const char *command); 

DESCRIPTION 

system ( ) executes the command specified by the string pointed to by command. The environment of the 
executed command is as if a child process were created using fork ( ) (see fork{2)\ and the child process 
invoked the sh-posix(l) utility via a call to exec 1 ( ) (see execl(2)) as follows: 

execl("/bIn/posix/sh", "sh", " -c" , command, 0); 

system () ignores the SIGINT and SIGQUIT signals, and blocks the SIGCHLD signal, while waiting 
for the command to terminate. If this might cause the application to miss a signal that would have killed it, 
the application should examine the return value from system ( ) and take whatever action is appropriate 
to the application if the command terminated due to receipt of a signal. 

system ( ) does not affect the termination status of any child of the calling processes other than the pro- 
cess or processes it itself creates. 

system ( ) does not return until the child process has terminated. 

Application Usage 

If the return value of system ( ) is not -1, its value can be decoded through the use of the macros 
described in <sys/ wait .h>. For convenience, these macros are also provided in <stdlib.h>. 

Note that, while system ( ) must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting for 
the child to terminate, the handling of signals in the executed command is as specified by fork(2) and 
exec(2). For example, if SIGINT is being caught or is set to SIG_DFL when system () is called, the 
child is started with SIGINT handling set to SIG_DFL. 

Ignoring SIGINT and SIGQUIT in the parent process prevents coordination problems (such as two 
processes reading from the same terminal) when the executed command ignores or catches one of the sig- 
nals. 

RETURN VALUE 

If command is null, system() returns non-zero. 

If command is not null, system ( ) returns the termination status of the command language interpreter 
in the format specified by waitpid{2). The termination status of the command language interpreter is as 
specified for sh-posix(l), except that if some error prevents the command language interpreter from execut- 
ing after the child process is created, the return value from system ( ) is as if the command language 
interpreter had terminated using _exit (127 ) . If a child process cannot be created, or if the termination 
status for the command language interpreter cannot be obtained, system () returns -1 and sets errno 
to indicate the error. 

DIAGNOSTICS 

syst em ( ) forks to create a child process which, in turn, exec ( ) s /bin/pos lx/sh in order to execute 
string. If the fork fails, system ( ) returns -1 and sets errno. If the exec fails, system ( ) returns the 
status value returned by waitpldO (see waitpid(2)) for a process that terminates with a call of 
exit (127). 

ERRORS 

If errors are encountered, system ( ) sets errno values as described by fork(2). 

FILES 

/bin/pos ix/sh 

SEE ALSO 

sh(l), fork(2), exec(2), waitpid(2). 

STANDARDS CONFORMANCE 

system ( ) : AES, SVID2, XPG2, XPG3, XPG4, POSIX.2, ANSI C 
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NAME 

tcgetattK), tcsetattrO - control tty device 

SYNOPSIS 

ttinclude <termlos.h> 

int tcgetattr(int fildes, struct termios *termios_p) ; 

int tcsetattr( 

int fildes, 

int opt ional_act ions, 

const struct termios *termios_p 
); 

DESCRIPTION 

tcgetattr ( ) gets the parameters associated with fildes and stores them in the termios structure refer- 
enced by termios_p. If the terminal device does not support split baud rates, the input baud rate stored in 
the termios structure is zero. This function is allowed from a background process (see termio(7)). However, 
the terminal attributes can be subsequently changed by a foreground process. 

tcsetattrO sets the parameters associated with fildes (unless support is required from underlying 
hardware that is not available) from the termios structure referenced by termios_p as follows: 

• If optional jxctions is TCSANOW, the change is immediate. 

• If optional jxctions is TCSADRAIN, the change occurs after all output written to fildes is transmit- 
ted. 

• If optional jxctions is TCSAPLUSH, the change occurs after all output written to fildes is transmit- 
ted, and all input that has been received but not read is discarded. 

RETURN VALUE 

Upon successful completion, a value of zero is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

tcgetattr ( ) and tcsetattr ( ) fail if any of the following conditions are encountered: 

[EBADF] fildes is not a valid file descriptor. 

[EINVAL] The optional jxctions argument is not a proper value. 

[ENOTTY] The file associated with fildes is not a terminal. 

WARNINGS 

A request to set a hardware parameter to a value that is not supported by the hardware being used is 
ignored. Any remaining parameter values in the request that are supported or that do not affect hardware 
are set as requested. For any hardware that does not support separate input and output baud rates, the 
requested output baud rate is used to set the actual hardware baud rate, tcgetattr ( ) always returns 
the actual values set in hardware. 

SEE ALSO 

cfspeed(3C), tccontrol(3C), termio(7). 

STANDARDS CONFORMANCE 

tcgetattr ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

tcsetattr ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

tcsendbreakQ, tcdrainO, tcflushQ, tcflow() - tty line control functions 

SYNOPSIS 

ttinclude <termios.h> 

int tcsendbreak(int fildes, int duration); 
int tcdrain(int fildes); 

int tcflush(int fildes, int queue_selector) ; 
int tcflow(int fildes, int action); 

DESCRIPTION 

If the terminal is using asynchronous serial data transmission, tcsendbreak ( ) causes transmission of 
a continuous stream of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. For all 
HP-UX implementations, duration is ignored. 

tcdrain ( ) waits until all output written to fildes has been transmitted. 

tcf lush( ) discards data written to fildes but not transmitted, or data received but not read, depending 
on the value of queue jselector: 

• If queuejselector is TCIFLUSH, data received but not read is flushed. 

• If queuejselector is TCOFLUSH, data written but not transmitted is flushed. 

• If queuejselector is TCIOFLUSH, both data received but not read, and data written but not 
transmitted is flushed. 

tcf low ( ) suspends transmission of data to fildes or reception of data from fildes , depending on the 
value of action: 

• If action is TCOOFF, output is suspended. 

• If action is TCOON, suspended output is restarted. 

• If action is TCIOFF, a STOP character is transmitted which is intended to cause the terminal to 
stop transmitting data to the system. 

• If action is TCION, a START character is transmitted which is intended to cause the terminal to 
start transmitting data to the system. 

RETURN VALUE 

Upon successful completion, a value of zero is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 

ERRORS 

These functions fail if one or more of the following is true: 

[EBADF] fildes is not a valid file descriptor. 

[EINTR] A signal was received during t cdr a in ( ) . 

[EINVAL] The queuejselector or the action argument is not a proper value. 

[ENOTTY] The file associated with fildes is not a terminal. 

SEE ALSO 

tcattribute(3C), tccontrol(3C), termio(7). 

STANDARDS CONFORMANCE 

tcdrain ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 

tcf low ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
tcf lush ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
tcsendbreak ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

tcgetpgrpO - get foreground process group id 

SYNOPSIS 

#include <unistd.h> 

pid_t tcgetpgrp(int fildes); 

DESCRIPTION 

tcgetpgrp ( ) returns the value of the process group ID of the foreground process group associated with 
the terminal referenced by fildes. tcgetpgrp ( ) is allowed from a process that is a member of a back- 
ground process group (see termio(7)); however, the information can be subsequently changed by a process 
that is a member of a foreground process group. 

RETURN VALUE 

Upon successful completion, tcgetpgrp ( ) returns the value of the process group ID of the foreground 
process group associated with the terminal referenced by fildes. Otherwise, tcgetpgrpO returns a 
value of -1 and sets errno to indicate the error. 

ERRORS 

tcgetpgrp ( ) fails if any of the following conditions are encountered: 

[EACCES] The file associated with fildes is the controlling terminal of the calling process, how- 

ever, there is no foreground process group defined for the controlling terminal. 

[EBADF] fildes is not a valid file descriptor. 

[ENOTTY] The file associated with fildes is not the controlling terminal or the calling process 

does not have a controlling terminal. 

WARNING 

The error EACCES, which is returned if the controlling terminal has no foreground process group, might not 
be returned in future releases, depending on the course taken by the POSIX standard. Portable applications 
therefore should not rely on this error condition. 

SEE ALSO 

setpgid(2), setsid(2), tcsetpgrp(3C), termio(7). 

STANDARDS CONFORMANCE 

tcgetpgrp ( ) : AES, XPG3, XPG4, FIPS 151-2, POSIX.l 
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NAME 

tcsetpgrpO - set foreground process group id 

SYNOPSIS 

ttinclude <unistd.h> 

int tcsetpgrp(int fildes, pid_t pgrp_id) ; 

DESCRIPTION 

If the calling process has a controlling terminal, tcsetpgrp ( ) sets the foreground process group ID asso- 
ciated with the terminal referenced by fildes to pgrp_id. The file associated with fildes must be the control- 
ling terminal of the calling process and the controlling terminal must be currently associated with the ses- 
sion of the calling process. The value of pgrp_id must match a process group ID of a process in the same 
session as the calling process. 

RETURN VALUE 

Upon successful completion, tcsetpgrpO returns zero. Otherwise, tcsetpgrpO returns -1 and sets 
errno to indicate the error. 

ERRORS 

tcsetpgrp ( ) fails if any of the following conditions are encountered: 

[EBADF] fildes is not a valid file descriptor. 

[EINVAL] The value of the pgrpj,d argument is not supported. 

[ENOTTY] The calling process does not have a controlling terminal, or the fildes is not the con- 

trolling terminal, or the controlling terminal is no longer associated with the session 
of the calling process. 

[EPERM] The value ofpgrpjd is a supported value but does not match the process group ID of 

a process in the same session as the calling process. 

SEE ALSO 

setpgid(2), setsid(2), tcgetpgrp(3C), termio(7). 

STANDARDS CONFORMANCE 

tcsetpgrp ( ) : AES, XPG3, XPG4, FTPS 151-2, POSDC.l 
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NAME 

tgetent(), tgetnumO, tgetflagO, tgetstr(), tgoto(), tputs() - emulate /etc/termcap access routines 

SYNOPSIS 

#include <curses.h> 

int tgetent (char *bp, const char *name); 

int tgetnum( const char *id); 

int tgetf lag (const char *id) ; 

char *tgetstr (const char *id, char **area) ; 

char *tgoto(char *cm, int destcol, int destline) ; 

int tputs(char *cp, int affcnt, int (*outc) (int) ) ; 

DESCRIPTION 

These functions extract and use capabilities from the compiled terminal capability data bases (see ter- 
minfo(4)). They are emulation routines that are provided as a part of the curses(3X) library. 

tgetent ( ) Extracts the compiled entry for terminal name into buffers accessible by the program- 
mer. Unlike previous termcap routines, all capability strings (except cursor address- 
ing and padding information) are already compiled and stored internally upon return 
from tgetent (). The buffer pointer bp is redundant in the emulation, and is 
ignored. It should not be relied upon to point to meaningful information, 
tgetent ( ) returns -1 if it cannot access the terminfo directory, if there is no capa- 
bility file for name, and 1 if all goes well. If a TERMINFO environment variable is 
set, tgetent ( ) first looks for TERMINFO/ 7 /name (where ? is the first character 
of name), and if that file is not accessible, it looks for 
/usr /l ib/t erminf o/ ? /name. 

tgetnum ( ) Gets the numeric value of capability id, returning -1 if it is not given for the terminal, 
tgetnum ( ) is useful only with capabilities having numeric values. 

tgetf lag ( ) Returns 1 if the specified capability is present in the terminal's entry, and if it is 
not. tgetf lag ( ) is useful only with capabilities that are boolean in nature (i.e. 
either present or missing in terminfoiA)). 

tgetstr ( ) Returns a pointer to the string value of capability id. In addition, if area is not a 
NULL pointer, tgetstr ( ) places the capability in the buffer at area and advances 
the area pointer. The returned string capability is compiled except for cursor address- 
ing and padding information, tgetstr ( ) is useful only with capabilities having 
string values. 

tgoto( ) Returns a cursor addressing string decoded from cm to go to column destcol in line 

destline. (Programs that call tgoto() should be sure to turn off the TAB3 bit or 
bits, since tgoto() can now output a tab. See termio{l)). Note that programs 
using termcap should in general turn off TAB3 anyway since some terminals use 
Ctrl-I for other functions, such as nondestructive space.) If a % sequence is given 
that is not understood, tgoto() returns [OOPS]. 

tputs ( ) Decodes the padding information of the string cp. affcnt gives the number of lines 

affected by the operation, or 1 if this is not applicable, outc is a routine that is called 
with each character in turn. The terminfo variable pad_char should contain a 
pad character to be used (from the pc capability) if a null ( A @) is inappropriate. 

FILES 

/usr/lib/libcurses.a -lcurses library 

/usr/lib/terminfo/?/* databases 

SEE ALSO 

ex(l), terminfo(4), termio(7). 



792 



HP-UX Release 9.0: August 1992 



tmpfile(3S) tmpfile(3S) 



NAME 

tmpfile() - create a temporary file 

SYNOPSIS 

ttinclude <stdio.h> 

FILE * tmpf ile( void); 

DESCRIPTION 

tmpf ile( ) creates a temporary file by generating a name through tmpnam( ) (see tmpnam (3S)), and 
returns a corresponding PILE pointer. If the file cannot be opened a NULL pointer is returned. The file is 
automatically deleted when the process using it terminates. The file is opened for update (wb+). 

NOTES 

On HP-UX systems, the wb+ mode is equivalent to the w+ mode. 

SEE ALSO 

creat(2), unlink(2), mktemp(3C), fopen(3S), tmpnam(3S). 

STANDARDS CONFORMANCE 

tmpf lie ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

tmpnam(), tempnam() - create a name for a temporary file 

SYNOPSIS 

#lnclude <stdio.h> 

char *tmpnam(char *s); 

char *tempnam( const char *dir / const char *pfx) ; 

DESCRIPTION 

tmpnam ( ) and tempnam ( ) generate file names that can safely be used for a temporary file. 

tmpnamO Always generates a file name using the path -prefix defined as P_tmpdir in the 
<3tdio.h> header file. If s is NULL, tmpnam () leaves its result in an internal 
static area and returns a pointer to that area. The next call to tmpnam ( ) destroys 
the contents of the area. If s is not NULL, it is assumed to be the address of an array 
of at least L_tmpnam bytes, where L_tmpnam is a constant defined in 
<stdio .h>; tmpnam( ) places its result in that array and returns s. 

tempnam ( ) allows the user to control the choice of a directory. The argument dir points to the 
name of the directory in which the file is to be created. If dir is NULL or points to a 
string that is not an appropriate directory name, the path-prefix defined as 
P__tmpdir in the <stdio.h> header file is used. If that directory is not accessible, 
/tmp is used as a last resort. This entire sequence can be eliminated by providing an 
environment variable TMPDIR in the user's environment, whose value is the name of 
the desired temporary-file directory. 

Many applications are written such that temporary files have certain initial character sequences in their 
names. Use the pfx argument to define a given prefix. The argument can be NULL or point to a string of 
up to five characters to be used as the first characters in the temporary-file name. 

tempnam ( ) uses malloc ( ) (see malloc(3C)) to get space for the constructed file name, and returns a 
pointer to this area. Thus, any pointer value returned from tempnam ( ) can serve as an argument to 
free() (see malloc(3C)). If tempnam () cannot return the expected result for any reason; i.e., mal- 
loc ( ) failed, or none of the above mentioned attempts to find an appropriate directory was successful, a 
NULL pointer is returned. 

NOTES 

tmpnam ( ) and tempnam ( ) generate a different file name each time they are called, but start recycling 
previously used names if called more than TMP_MAX times in a single process. 

Files created using these functions and either fopen() or creat () (see fopen(SS) and creat(2)) are 
temporary only in the sense that they reside in a directory intended for temporary use, and their names are 
unique. It is the user's responsibility to use unlink{2) to remove the file when it is no longer needed. 

WARNINGS 

Between the time a file name is created and the file is opened, it is possible for some other process to create 
a file with the same name. This can never happen if that other process is using these functions or mkt emp, 
and the file names are chosen such that duplication by other means is unlikely. 

SEE ALSO 

creat(2), unlink(2), malloc(3C), mktemp(3C), fopen(3S), tmpfile(3S). 

STANDARDS CONFORMANCE 

tmpnam ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 

tempnam ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

sin(), cos(), tan(), asin(), acos(), atan(), atan2(), sinfO, cosfQ, tanf(), asinf()> acosfD, atanfO, atan2f() - tri- 
gonometric functions 

SYNOPSIS 

#include <math.h> 

double sin (double x) ; 

double cos (double x) ; 

double tan (double x) ; 

double asln(double x); 

double acos (double x) ; 

double atan(double x) ; 

double atan2 (double y, double x) ; 

float slnf (float x) ; 

float cosf (float x) ; 

float tanf (float x) ; 

float asinf( float x) ; 

float acosf( float x) ; 

float atanf( float x) ; 

float atan2f (float y, float x) ; 

DESCRIPTION 

The following trigonometric functions return the values indicated: 

s in {x ) sine of x (x specified in radians) 

cos {x ) cosine of x (x specified in radians) 

tan (x ) tangent of x (x specified in radians) 

as in (x ) arcsine of x in the range -n/2 to 7t/2. 

acos {x ) arccosine of x in the range to rc. 

at an (a:) arctangent of x in the range -n/2 to tc/2. If x is UNFINITY , atan( ) returns ±n/2 

respectively. 

at an2 (y , x ) arctangent ofy/x, in the range -n to k, using the signs of both arguments to determine 
the quadrant of the return value. 

Other atan2 ( ) returns: 

• rc/4 wheny and x are +INFINITY. 

• 3 *tc/4 when y is +INFINITY and a: is -INFINITY. 

• -tc/4 when y is -INFINITY and x is +INFINITY. 

• -3 *rc/4 when y and x are -INFINITY. 

• 0.0 when y is 0.0 and a: is a positive number. 

• n when y is 0.0 and re is a negative number, or -n when y is -0.0 and a: is a 
negative number. 

• tc/2 when y is a positive number and x is 0.0, or -n/2 when y is a negative 
number and* is 0.0. 

• ±7u/2 ify/x would overflow. The result will be n/2 if y is a positive number and 
-rc/2 if y is a negative number. 

• ±n or 0.0 ify/x would underflow. The result is 0.0 if a: is a positive number, % 
if a; is a negative number and y is a positive number, and -tc if x and y are 
both negative numbers. 
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sinf (), cosf (), tanf (), asinf (), acosf (), atanf (), and atan2f() are float versions of 
these functions; they take float arguments and return float results. Their performance is 
significantly faster than that of the double versions of the functions. Programs must be compiled in 
ANSI mode (use the -Aa option) in order to use these functions; otherwise, the compiler promotes the 
float arguments to double, and the functions return incorrect results. 

DEPENDENCIES 
Series 300/400 

sinf (), cosf (), tanf (), asinf (), acosf (), atanf (), and atan2f () are not supported on 
Series 300/400 systems. 

Series 700/800 

sinf ( ) , cosf ( ) , tanf ( ) , asinf ( ) , acosf ( ) , atanf ( ) , and atan2f ( ) are not specified by any 

B+.smrlssrrl fthov arc \\rtvaa\ro-r -namoA in txconrAa-nna wi+n Hid mmmntiriTH onaoifio/1 ir> + ™e "TiNifciivo T.iKrorv 

Directions" section of the ANSI C standard). These functions are provided in the PA1.1 versions of the math 
library only. The +DA1 . 1 option (the default on Series 700 systems) links in a PA1.1 version automati- 
cally. A PA1.1 library can be linked in explicitly. For more information, see the HP-UX Floating-Point 
Guide. 

ERRORS 
/lib/libm.a 

sin(), cos(), and tan() lose accuracy when their argument is far from zero. For arguments 
sufficiently large, these functions return 0.0 when there would otherwise be a complete loss of significance. 
In this case a message indicating TLOSS error is printed on the standard error output. For less extreme 
arguments causing partial loss of significance, a PLOSS error is generated but no message is printed. In 
both cases, errno is set to ERANGE. 

If the magnitude of the argument of asin() or acos ( ) is greater than one, or if both arguments of 
atan2 ( ) are 0.0, 0.0 is returned and errno is set to EDOM. In addition, a message indicating DOMAIN 
error is printed on the standard error output. 

sin ( ) , cos ( ) , tan ( ) , acos ( ) , and as in ( ) return NaN and set errno to EDOM when x is NaN or 
±INFINITY. In addition, a message indicating DOMAIN error is printed on the standard error output. 

atan() returns NaN and sets errno to EDOM when x is NaN. In addition, a message indicating 
DOMAIN error is printed on the standard error output. 

atan2 ( ) returns NaN and sets errno to EDOM when x ory is NaN. In addition, a message indicating 
DOMAIN error is printed on the standard error output. 

These error-handling procedures can be changed with the matherr ( ) function (see matherr(SM.)). 

/lib/libM.a 

No error messages are printed on the standard error output. 

sin(), cos(), and tan() lose accuracy when their argument is far from zero. For arguments 
sufficiently large, these functions return 0.0 when there would otherwise be a complete loss of significance. 
For less extreme arguments causing partial loss of significance, a PLOSS error is generated. In both cases, 
errno is set to ERANGE. 

If the magnitude of the argument of asin() or acos ( ) is greater than one, NaN is returned and 
errno is set to EDOM. 

If both arguments of atan2 ( ) are 0.0, 0.0 is returned and errno is set to EDOM. 

s in ( ) , cos ( ) , t an ( ) , acos ( ) , and as in ( ) return NaN and set errno to EDOM when x is NaN or 

INFINITY. 

at an ( ) returns NaN and sets errno to EDOM when x is NaN. 

at an 2 ( ) returns NaN and sets errno to EDOM when x or y is NaN. 

These error-handling procedures can be changed with the function _matherr ( ) (see matherr(2M)). Note 
that _matherr() is provided in order to assist in migrating programs from libm.ato libM.aandis 
not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

trigd(3M), isinf(3M), isnan(3M), matherr(3M). 
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STANDARDS CONFORMANCE 

acos ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
acos ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

asin ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
as in ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

at an ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
at an ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

atan2 ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
atan2 ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

cos ( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
cos ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

sin( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
sin ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 

tan( ) in libm.a: AES, SVID2, XPG2, XPG3, FIPS 151-2, POSIX.l 
tan ( ) in libM.a: AES, XPG3, XPG4, FIPS 151-2, POSIX.l, ANSI C 
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NAME 

sind(), cosd(), tand(), asind(), acosd(), atand(), atan2d(), sindf(), cosdf(), tandf(), asindf(), acosdf(), 
atandf(), atan2df() - degree-valued trigonometric functions 

SYNOPSIS 

#include <math.h> 

double sind(double x) ; 

double cosd(double x) ; 

double tand(double x) ; 

double aslnd (double x) ; 

double acosd (double x) ; 

double atand (double x) ; 

double atan2d(double y, double x) ; 

float slndf (float x) ; 

float cosdf (float x) ; 

float tandf (float x) ; 

float asindf (float x) ; 

float acosdf (float x); 

float atandf (float x) ; 

float atan2df (float y, float x) ; 

DESCRIPTION 

sindQ, cosd(), tand(), aslnd(), acosd(), atand(), and atan2d() are degree-valued ver- 
sions of the trigonometric functions. The functions return the values indicated: 

sind() sine of x (x specified in degrees) 

cos ( ) cosine of x (x specified in degrees) 

tand ( ) tangent of re (x specified in degrees) 

as ind ( ) arcsine of x in the range -90 to 90. 

acosd ( ) arccosine of x in the range to 180. 

atand ( ) arctangent of x in the range -90 to 90. If x is ±INFINITY , atand () returns ±90 

respectively. 

atan2d() arctangent of y/x, in the range -180 to 180, using the signs of both arguments to 
determine the quadrant of the return value. 

Other atan2d() returns: 

• 45 wheny and x are +INFINITY. 

• 135 when y is +INFINITY and x is -INFINITY. 

• -45 when y is -INFINITY and x is +INFINITY. 

• -135 when y and x are -INFINITY. 

• 0.0 wheny is 0.0 and x is a positive number. 

• 180 wheny is 0.0 and a; is a negative number, or -180 wheny is -0.0 and x is 
a negative number. 

• 90 when y is a positive number and x is 0.0, or -90 when y is a negative 
number and x is 0.0. 

• ±90 if y/x would overflow. The result will be 90 if y is a positive number and 
-90 if y is a negative number. 

• ±180 or 0.0 if y/x would underflow. The result will be 0.0 if * is a positive 
number, 180 if x is a negative number andy is a positive number, and -180 
if x andy are both negative numbers. 
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sindf ( ), cosdf (), tandf (), asindf ( ), cosdf (), atandf (), and atan2df ( ) are float ver- 
sions of these functions; they take float arguments and return float results. They are named in 
accordance with the conventions specified in the "Future Library Directions" section of the ANSI C stan- 
dard. Their performance is significantly faster than that of the double versions of the functions. Com- 
piling must be done in ANSI mode (use the -Aa option) in order to use these functions; otherwise, the com- 
piler promotes the float arguments to double, and the functions return incorrect results. 

DEPENDENCIES 
Series 300/400 

These functions are not supported on the Series 300/400. 

Series 700/800 

These functions are provided in the PA1.1 versions of the math library only. The +DA1 . 1 option (the 
default on Series 700 systems) links in a PA1.1 version automatically. A PAl.l library can be linked in expli- 
citly. For more information, see the HP-UX Floating-Point Guide. 

ERRORS 

/lib/libm.a 

slnd(), cosd(), and tand() lose accuracy when their argument is far from zero. For arguments 
sufficiently large, these functions return when there would otherwise be a complete loss of significance. In 
this case a message indicating TLOSS error is printed on the standard error output. For less extreme 
arguments causing partial loss of significance, a PLOSS error is generated but no message is printed. In 
both cases, errno is set to ERANGE. 

If the magnitude of the argument of asind( ) or acosd( ) is greater than one, or if both arguments of 
atan2d ( ) are 0.0, is returned and errno is set to EDOM. In addition, a message indicating DOMAIN 
error is printed on the standard error output. 

slnd(), cosd(), tand(), acosd(), and aslnd() return NaN and set errno to EDOM when x is 
NaN or 1INFINITY. In addition, a message indicating DOMAIN error is printed on the standard error out- 
put. 

atand( ) returns NaN and sets errno to EDOM when x is NaN. In addition, a message indicating 
DOMAIN error is printed on the standard error output. 

atan2d ( ) returns NaN and sets errno to EDOM when x or y is NaN. In addition, a message indicating 
DOMAIN error is printed on the standard error output. 

These error-handling procedures can be changed with the matherr ( ) function (see matherr($M.)). 

/lib/libM.a 

No error messages are printed on the standard error output. 

slnd(), cosd(), and tand() lose accuracy when their argument is far from zero. For arguments 
sufficiently large, these functions return when there would otherwise be a complete loss of significance. 
For less extreme arguments causing partial loss of significance, a PLOSS error is generated. In both cases, 
errno is set to ERANGE. 

If the magnitude of the argument of asind() or acosd( ) is greater than one, NaN is returned and 
errno is set to EDOM. 

If both arguments of atan2d ( ) are 0.0, is returned and errno is set to EDOM. 

slnd ( ) , cosd ( ) , tand ( ) , acosd ( ) , and asind ( ) return NaN and set errno to EDOM when x is 
NaN or INFINITY. 

at and ( ) returns NaN and sets errno to EDOM when x is NaN. 

atan2d ( ) returns NaN and sets errno to EDOM when x ory is NaN. 

These error-handling procedures can be changed with the function _mather r ( ) (see matherr (3M)). Note 
that _matherr ( ) is provided in order to assist in migrating programs from 1 ibm. a to llbM . a and is 
not a part of XPG3, ANSI C, or POSIX. 

SEE ALSO 

trig(3M), isinf(3M), isnan(3M), matherr(3M). 
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NAME 

tsearch(), tfind(), tdelete(), twalk() - manage binary search trees 

SYNOPSIS 

#include < search. h> 

void *tsearch( 

const voj.d. *key, 

void **rootp, 

int (*compar) (const void *, const void *) 
); 

void *tfind( 

const void *key, 

void * const *rootp, 

int (*compar) (const void *, const void *) 
); 

void *tdelete( 

const void *key, 

void **rootp, 

int (*compar) (const void *, const void *) 
); 

void twalk ( 

const void *root, 

void (*action) (const void *, VISIT, int) 
); 

DESCRIPTION 

tsearch ( ) , tf ind ( ) , tdelete ( ) , and twalk ( ) are routines for manipulating binary search trees. 
They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are done with a user- 
supplied routine, compar. This routine is called with two arguments, the pointers to the elements being 
compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argu- 
ment is to be considered less than, equal to or greater than the second argument. The comparison function 
need not compare every byte, so arbitrary data may be contained in the elements in addition to the values 
being compared. 

tsearch ( ) is used to build and access the tree, key is a pointer to an entry to be accessed or stored. If 
there is an entry in the tree equal to the value pointed to by key, a pointer to the previous key associated 
with this found entry is returned. Otherwise, key is inserted, and a pointer to it returned. Note that since 
the value returned is a pointer to key and key itself is a pointer, the value returned is a pointer to a pointer. 
Only pointers are copied, so the calling routine must store the data, rootp points to a variable that points to 
the root of the tree. A NULL value for the variable pointed to by rootp denotes an empty tree; in this case, 
the variable is set to point to the entry which will be at the root of the new tree. 

Like tsearch ( ), tfind() searches for an entry in the tree, returning a pointer to it if found. However, 
if it is not found, tfind() returns a NULL pointer. The arguments for tfind() are the same as for 
tsearch ( ). 

tdelete ( ) deletes a node from a binary search tree. Arguments are the same as for tsearch ( ) . The 
variable pointed to by rootp is changed if the deleted node was the root of the tree, tdelete ( ) returns a 
pointer to the parent of the deleted node, or a NULL pointer if the node is not found. 

twalk ( ) traverses a binary search tree, root is the root of the tree to be traversed. (Any node in a tree 
may be used as the root for a walk below that node.) action is the name of a routine to be invoked at each 
node. This routine is, in turn, called with three arguments: 

• First argument is the address of the node being visited. 

• Second argument is a value from an enumeration data type typedef enum { preorder, 
postorder, endorder, leaf } VISIT; (defined in the <search.h> header file), 
depending on whether this is the first, second or third time that the node has been visited (during 
a depth-first, left-to-right traversal of the tree), or whether the node is a leaf. 
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• Third argument is the level of the node in the tree, with the root being level zero. 

EXAMPLE 

The following code reads strings, and stores structures containing a pointer to each string and a count of its 
length. It then walks the tree, printing out the stored strings and their lengths in alphabetical order. 

.C ttinclude <stdlib.h> 

.C #include <search.h> 

.C #include <stdio.h> 

.C ftinclude <string.h> 

.IP 

.C struct element /* pointers to 

• C { 

.C char *string;" 
.C int length;" 

• C }; 

.C char strlng_space [10000] ; /* space to 

struct element elements [500] ; /* elements to store */ 

struct element *root = NULL; /* this points to the root */ 

void print_node (void *, VISIT, int); 

int element_compare (const void *, const void *); 

main( ) 
{ 

char *strptr = string_space; 

struct element *element_ptr = elements; 

struct element **ts_retval; 

int 1 = 0; 

while (gets(strptr) != NULL && i++ < 500) 
{ 

/* set element */ 
element_ptr->string = strptr; 
element_ptr-> length = strlen (strptr) ; 

/* put element into the tree */ 

ts_retval = (struct element **) tsearch( (void *) element_ptr / 
(void **) &root, element_compare) ; 

if (*ts_retval == element_ptr) 
{ 

(void) printf("The element \"%a\" ", 
(*ts_retval)->string) ; 

(void) printf("has now been inserted into the tree\n"); 
} 

else 
{ 

(void) printf("The element \"%s\" ", 
(*ts_retval)->string) ; 

(void) printf ( "already existed in the tree\n" ); 
} 

/* adjust pointers, so we don't overwrite tree */ 
strptr += element_ptr-> length + 1; 
e 1 ement_pt r + + ; 
} 

twalk((void *) root, print_node) ; 
} 
/* This routine compares two elements, based on an 

alphabetical ordering of the string field. */ 
int 
element_compare(eleml, elem2) 
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void *eleml / *elem2; 
{ 

return strcmp( ( (struct element *) eleml) ->string, 
((struct element *) elem2) ->strlng) ; 
} 
/* This routine prints out a node, the first time 

twalk. encounters it. */ 
void 

print_node (element, order, level) 
void *element; 
VISIT order; 
int level; 
{ 

if (order == preorder I I order == leaf) 



{ 



(void) print f ("string = %2 0s, length = %d\n", 

(♦(struct element **) element ) ->string, 
(♦(struct element **) element) ->length) ; 



SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

RETURN VALUE 

A NULL pointer is returned by t search ( ) if there is not enough space available to create a new node. 

A NULL pointer is returned by tsearch ( ) , t f ind ( ) , and tdelete ( ) if rootp is NULL on entry. 

If the datum is found, both tsearch () and tfind() return a pointer to it. If not, tfind() returns 
NULL, and tsearch ( ) returns a pointer to the inserted item. 

WARNINGS 

The root argument to twalk ( ) is one level of indirection less than the rootp arguments to tsearch ( ) 
and tdelete () . 

Two nomenclatures are used to refer to the order in which tree nodes are visited. tsearch() uses 
preorder, postorder and endorder to respectively refer to visting a node before any of its children, after its 
left child and before its right and after both its children. The alternate nomenclature uses preorder, 
inorder, and postorder to refer to the same visits, which could result in some confusion over the meaning of 
postorder. If the calling function alters the pointer to the root, results are unpredictable. 

STANDARDS CONFORMANCE 

tsearch ( ) : AES, SVID2, XPG2, XPG3, XPG4 

tdelete () : AES, SVID2, XPG2, XPG3, XPG4 
tf ind ( ) : AES, SVID2, XPG2, XPG3, XPG4 
twalk ( ) : AES, SVID2, XPG2, XPG3, XPG4 
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NAME 

ttyname(), isattyO - find name of a terminal 

SYNOPSIS 

ftinclude <unistd.h> 

char *ttyname(int fildes); 
int isatty(int fildes); 

DESCRIPTION 

ttyname ( ) returns a pointer to a string containing the null-terminated path name of the terminal device 
associated with file descriptor fildes. 

isatty ( ) returns 1 if fildes is associated with a terminal device, otherwise. 

RETURN VALUE 

ttyname ( ) returns a NULL pointer if fildes does not describe a terminal device in directory /dev. 

ERRORS 

isatty () and ttyname () fail if any of the following conditions are encountered: 

[EBADF] The fildes argument is invalid. 

[ENOTTY] An inappropriate I/O control operation has been attempted. 

WARNINGS 

The return value points to static data whose content is overwritten by each call. 

FILES 

/dev/* 
/dev/pty/* 

STANDARDS CONFORMANCE 

ttyname ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.l 



isatty ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l 
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NAME 

ttyslot() - find the slot in the utmp file of the current user 

SYNOPSIS 

#include <unistd.h> 

int ttyslot (void) ; 

DESCRIPTION 

ttyslot () returns the index of the current user's entry in the /etc /utmp file. This is accomplished by 
scanning /etc /utmp for the name of the terminal associated with the standard input, standard output, 
or standard error (file descriptor 0, 1 or 2). 

RETURN VALUE 

ttyslot ( ) returns -1 if an error was encountered while searching for the terminal name or if none of file 
descriptors 0, 1, or 2 is associated with a terminal device. 

FILES 

/etc/utmp 

SEE ALSO 

getut(3C), ttyname(3C). 

STANDARDS CONFORMANCE 

ttyslot ():XPG2 
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NAME 

ungetc() - push character back into input stream 

SYNOPSIS 

#include <stdio.h> 

int ungetc (int c, FILE * stream) ; 

DESCRIPTION 

ungetc ( ) inserts the character c (converted to an unsigned char) into the buffer associated with an input 
stream. That character, c, is returned by the next call to getc ( ) (see getc(3S)) on that stream. A success- 
ful intervening call to a file positioning function with stream (£.aeek() ; faetpoaf). or rewindf)) 
erases all memory of the inserted characters. 

ungetc ( ) affects only the buffer associated with the input stream. It does not affect the contents of the 
file corresponding to stream . 

One character of pushback is guaranteed. 

If c equals EOF, ungetc ( ) does nothing to the buffer and returns EOF. 

RETURN VALUE 

If successful, ungetc ( ) returns c and clears the end-of-file indicator for the stream, ungetc ( ) returns 
EOF if it cannot insert the character. 

SEE ALSO 

fseek(3S), fsetpos(3S), getc(3S), setbuf(3S). 

STANDARDS CONFORMANCE 

ungetc ( ) : AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSLX.l, ANSI C 
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NAME 

ungetwcO - push a wide character back into an input stream 

SYNOPSIS 

#include <wchar.h> 

wint_t ungetwc (wint_t wc, PILE *stream) ; 

ixemarKS; 

This function is comphant with the XPG4 Worldwide Portability Interface wide-character I/O functions. It 
parallels the 8-bit character I/O function defined in ungetc(3S). 

DESCRIPTION 

ungetwc ( ) pushes the character corresponding to the wide-character code wc into the buffer associated 
with an input stream. That wide-character code, wc, is returned by the next call to getwc ( ) (see 
getwc(3C)) on that stream. A successful intervening call to a file positioning function with stream 
(f seek ( ) , f setpos ( ) , or rewind ( ) ) erases all memory of the pushed-back characters. 

ungetwc ( ) affects only the buffer associated with the input stream. It does not affect the contents of the 
file corresponding to stream . 

One character of pushback is guaranteed. 

If wc equals WEOP, ungetwcO does nothing to the buffer and returns WEOP. 

The definition for this function, the type wint_t and the value WEOP are provided in the <wchar . h> 
header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If successful, ungetwc ( ) returns wc and clears the end-of-file indicator for the stream, ungetwc ( ) 
returns WEOP if it cannot insert the wide character. 

SEE ALSO 

fseek(3S), fsetpos(3S), getwc(3C), setbuf(3S). 

STANDARDS CONFORMANCE 

ungetwc ( ) : XPG4 
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NAME 

vprintf(), vfprintfQ, vsprintfO - print formatted output of a varargs argument list 

SYNOPSIS 

#include <stdio.h> 
ttinclude <varargs.h> 

int vprintf (const char ♦format, va_list ap); 

int vfprintf (PILE ♦stream, const char *format, va_list ap) ; 

int vsprintf (char *s, const char *format, va_list ap); 

DESCRIPTION 

vprintf (), vfprintf (), and vsprintfO are the same as printf (), fprintfO, and 
sprint f ( ) respectively, except that instead of being called with a variable number of arguments, they 
are called with an argument list as defined by varargs(5). 

EXAMPLE 

The following demonstrates how vfprintf ( ) could be used to write an error routine: 

ttinclude <stdio.h> 
#inc lude <varargs . h> 



/* 

* error should be called using the form 

* error (function_name, format, argl, arg2 . . . ) ; 
*/ 

/*VARARGS0*/ 

void 

error (va_alist ) 

va_dcl 

{ 

va_list args; 

char *fmt; 

va_start (args) ; 

/* print out name of function causing error */ 

(void) f printf (stderr, "ERROR in %s : ", va_arg(args, char *)); 

fmt = va_arg(args, char *); 

/* print out remainder of message */ 
(void) vfprintf (stderr, fmt, args); 
va_end(args) ; 
(void) abort ( ) ; 
} 

SEE ALSO 

setlocale(3C), printf(3S), varargs(5). 

STANDARDS CONFORMANCE 

vprintf ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 

vfprintf ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 
vsprintf ( ) : AES, SVID2, XPG2, XPG3, XPG4, ANSI C 



HP-UX Release 9.0: August 1992 - 1 - 807 



vscanf(3S) vscanf(3S) 



NAME 

vscanf(), vfscanf(), vsscanf() - formatted input conversion to a varargs argument list, read from stream file 

SYNOPSIS 

#include <stdio.h> 
#include <varargs.h> 

int vscanf (const char *fiormat,- va_list ap) ; 

int vfscanf (FILE *stream, const char ♦format, va_list ap); 

int vsscanf(char *s, const char *format, va_list ap) ; 

DESCRIPTION 

vscanf ( ) , vfscanf ( ) , and vsscanf ( ) are the same as scanf ( ) , f scanf ( ) , and sscanf ( ) 
respectively, except that instead of being called with a variable number of arguments, they are called with 
an argument list as defined by varargs(5). 

SEE ALSO 

scanf(3S), setlocale(3C), varargs(5). 
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NAME 

towupperQ, towlowerO - translate wide characters 

SYNOPSIS 

ttinclude <wchar.h> 

wint_t towupper (wint_t wc) ; 
wint_t towlower (wint_t wc) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character conversion 
functions. They parallel the 8-bit character conversion functions defined in conv(3C) . 

DESCRIPTION 

towupper () and towlowerO have as domain a wint_t, the value of which is representable as a 
wchar_t or the value WEOP. If the argument has any other value, the behavior is undefined. If the argu- 
ment of towupper ( ) represents a lowercase letter, the result is the corresponding uppercase letter. If 
the argument of towlower ( ) represents an uppercase letter, the result is the corresponding lowercase 
letter. All other arguments are returned unchanged. 

Definitions for these functions, the types wlnt_t, wchar_t, and the value WEOF are provided in the 
<wchar . h> header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the translations to be done. 

International Code Set Support 

Single-byte character code sets are supported. Japanese HP15 and EUC multi-byte character code sets are 
supported, towupper ( ) and towlower ( ) return their argument for values in other multi-byte char- 
acter code sets outside the ASCII range. 

WARNING 

towupper ( ) and towlower ( ) are supplied both as library functions and as macros defined in the 
<wchar . h> header. Normally, the macro versions are used. To obtain the library function, either use a 
#undef to remove the macro definition or, if compiling in ANSI C mode, enclose the function name in 
parenthesis or take its address. The following examples use the library function for towlower ( ) : 

#include <wchar.h> 
#undef towlower 

main() 
{ 

cl = towlower(c); 



#include <wchar.h> 

main() 
{ 

wint_t (*conv_func) () ; 

cl = (towlower) (c) ; 

conv_func = towlower; 



AUTHOR 

wconv ( ) was developed by AT&T and HP. 
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SEE ALSO 

conv(3C), multibyte(3C), wctype(3C), setlocale(3C), lang(5). 

STANDARDS CONFORMANCE 

towlower():XPG4 

towupper ( ) : XPG4 



I 
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NAME 

wcsftimeO - convert date and time to wide-character string 

SYNOPSIS 

ttinclude <wchar.h> 

size_t wcsftime( 

wchar_t *ws , 

size_t maxsize, 

const char * format, 

const struct tm *timeptr 
); 

Remarks: 

This function is compliant with the XPG4 Worldwide Portability Interface wide-character formatting func- 
tions. It parallels the 8-bit character formatting function denned in strftime(3C). 

DESCRIPTION 

wcsf time ( ) converts the contents of a tm structure (see ctime(3C)) to a formatted date and time wide- 
character string. 

wcsf time ( ) places wide characters into the array pointed to by ws as controlled by the string pointed to 
by format. The format string consists of zero or more directives and ordinary characters. A directive con- 
sists of a % character, an optional field width and precision specification, and a terminating character that 
determines the directive's behavior. All ordinary characters (including the terminating null character) are 
converted into corresponding wide characters and are copied into the array. No more than maxsize wide 
characters are placed into the array. Each directive is replaced by the appropriate wide characters as 
described in the following list. The appropriate wide characters are determined by the program's locale, by 
the values contained in the structure pointed to by timeptr, and by the TZ environment variable (see 
External Influences below). 

The definition for this function and the type wchar_t are provided in the <wchar . h> header. 

Directives 

The following directives, shown without the optional field width and precision specification, are replaced by 
the corresponding wide characters as indicated: 

%a locale's abbreviated weekday name 

%h locale's full weekday name 

%b locale's abbreviated month name 

%B locale's full month name 

%c locale's appropriate date and time representation 

%d day of the month as a decimal number [01,31] 

%E locale's combined Emperor/Era name and year 

%H hour (24-hour clock) as a decimal number [00,23] 

%I hour (12-hour clock) as a decimal number [01,12] 

%j day of the year as a decimal number [001,366] 

%m month as a decimal number [01,12] H 

%M minute as a decimal number [00,59] | 

%n new-line wide character 

%N locale's Emperor/Era name 

%o locale's Emperor/Era year 

%p locale's equivalent of either AM or PM 

%S second as a decimal number [00,61] 

%t tab wide character 

%XJ week number of the year (the first Sunday as the first day of week 1) as a decimal number 

[00,53] 
%vr weekday as a decimal number [0(Sunday),6] 

%W week number of the year (the first Monday as the first day of week 1) as a decimal number 

[00,53] 
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%x. locale's appropriate date representation 

%X locale's appropriate time representation 

%Y year without century as a decimal number [00,99] 

%Y year with century as a decimal number 

%Z time zone name (or by no characters if no time zone exists) 

%% Percent character (%) 

The following directives are provided for backward compatibility with the directives supported by the 
date command and the ctime ( ) functions (see date(l) and ctime(3C)). It is recommended that the 
directives above be used in preference to those below. 

%D date in usual U.S. format (%m/%d/%y) (use %x instead) 

%S locale's full month name (use %B instead) 

%h locale's abbreviated month name (use %b instead) 

%r time in 12-hour U.S. format (%I:%M:%S [AM | PM]) (use %X instead) 

%1 time in 24-hour U.S. format (%H:%M:%S) (use %X instead) 

%z time zone name (or by no characters if no time zone exists) (use %Z instead) 

If a directive is not one of the above, the behavior is undefined. 

Field Width and Precision 

An optional field width and precision specification can immediately follow the initial % of a directive in the 
following order: 

[- I 0]u; the decimal digit string w specifies a minimum field width in which the result of the 

conversion is right- or left-justified. It is right-justified (with space padding) by 
default. If the optional - character is specified, it is left-justified with space padding 
on the right. If the optional character is specified, it is right-justified and padded 
with zeros on the left. 

.p the decimal digit string/? specifies the minimum number of digits to appear for the d, 

H, I, j, m, M, o, S, U, w, W, y and Y directives, and the maximum number of 
corresponding wide characters to be used from the a, A, b, B, c, D, E, F, h, n, N, p, r, 
t, T, x, X, z, Z, and % directives. In the first case, if a directive supplies fewer digits 
than specified by the precision, it is expanded with leading zeros. In the second case, 
if a directive supplies more characters than specified by the precision, excess charac- 
ters are truncated on the right. 

If no field width or precision is specified for a d, H, I, m, M, S, U, W, y, or j directive, a default of . 2 is 
used for all but j for which . 3 is used. 

EXTERNAL INFLUENCES 
Locale 

The LC_TIME category determines the characters to be substituted for those directives described above as 
being from the locale. 

The LC_CTYPE category determines the interpretation of the bytes within format as single and/or multi- 
byte characters as well as how wide-character conversions are done. 

The LCJNUMERIC category determines the characters used to form numbers for those directives that pro- 
duce numbers in the output. If ALT_DIGITS (see langinfo(5)) is defined for the locale, the characters so 
specified are used in place of the default ASCII characters. 

Environment Variables 

TZ determines the time zone name substituted for the %Z and %z directives. The time zone name is 
determined by calling the function tzset() which sets the external variable tzname (see c#me(3C)). 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If the total number of resulting wide characters including the terminating null wide character is not more 
than maxsize, wcsf time ( ) returns the number of wide characters placed into the array pointed to by 
ws, not including the terminating null wide character. Otherwise, zero is returned and the contents of the 
array are indeterminate. 
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EXAMPLES 

If the timeptr argument contains the following values: 



timeptr- 
timeptr- 
timeptr- 
timeptr- 
timeptr- 
timeptr- 
timeptr- 
timeptr- 
timeptr- 



>tm_sec = 4 ; 
>tm_min =9; 
>tm_hour = 15; 
>tm_mday =4; 
>tm_mon = 6; 
>tm_year = 88; 
>tm wda v = 1 - 
>tm_yday = 185; 
>tm_isdst =1; 



the following combinations of the LC_TIME category and format strings produce the indicated output: 



LC_TIMB 


Format String 


Output 


american 


%x 






Mon, Jul 4, 1988 


german 


%x 






Mo., 4. Juli 1988 


american 


%X 






03:09:04 PM 


french 


%X 






15h09 04 


anyt 


%H: 


%M 


•%S 


15:09:04 


anyj 


%.1H:%.1M:%.1S 


15:9:4 


any\ 


%2. 


1H 


%-3M:%03.1S 


15:9 :004 



t The directives used in these examples are not affected by the LC_TIME category of the locale. 

WARNINGS 

The function tzset ( ) is called upon every invocation of wcsf time ( ) (whether or not the time zone 
name is copied to the output array). 

The range of values for %S ([0,61]) extends to 61 to allow for the occasional one or two leap seconds. How- 
ever, the system does not accumulate leap seconds and the tm structure generated by the functions 
localt ime ( ) and gmt ime ( ) (see ctime(3C)) never reflects any leap seconds. 

Results are undefined if values contained in the structure pointed to by timeptr exceed the ranges defined 
for the tm structure (see dime (3C)) or are not consistent (such as if the tm_yday element is set to 0, indi- 
cating the first day of January, while the tm_mon element is set to 11, indicating a day in December). 

AUTHOR 

wcsf time ( ) was developed by HP. 

SEE ALSO 

date(l), ctime(3C), setlocale(3C), environ(5), langinfo(5), hpnls(5). 

STANDARDS CONFORMANCE 

wcsftime():XPG4 



I 
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NAME 

wcstod() - convert wide character string to double-precision number 

SYNOPSIS 

#include <wchar.h> 

double wcstod (const wchar_t *nptr, wchar_t **endptr) ; 

Remarks: 

This function is compliant with the XPG4 Worldwide Portability Interface wide-character formatting func- 
tions. It parallels the 8-bit character formatting function denned in strtod(3C). 

DESCRIPTION 

wcstod ( ) returns, as a double-precision floating-point number, the value represented by the wide charac- 
ter string pointed to by nptr. The wide character string is scanned (leading white-space characters as 
denned by iswspace ( ) in wctype(3C) are ignored) up to the first unrecognized character. If no conver- 
sion can take place, zero is returned. 

wcstod ( ) recognizes wide characters in the following sequence: 

1. An optional string of "white-space" wide characters which are ignored, 

2. An optional sign, 

3. A string of digits optionally containing a radix character, 

4. An optional e or E followed by an optional sign or space, followed by an integer. 

The radix character is determined by the current NLS environment (see setlocale(SC)). If set locale ( ) 
has not been called successfully, the default NLS environment, "C", is used (see lang(5)). The default 
environment specifies a period (.) as the radix character. 

If the value oiendptr is not (wchar_t **)NULL, the variable to which it points is set to point at the 
wide character after the last number, if any, that was recognized. If no number can be formed, *endptr is 
set to nptr, and zero is returned. 

The definition for this function and the type wchar_t are provided in the <wchar . h> header. 

EXTERNAL INFLUENCES 
Locale 

The LC_NUMERIC category determines the value of the radix character within the currently loaded NLS 
environment. 

The LC_CTYPE category determines how wide character codes are interpreted. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

If the correct value would cause overflow, +HUGE_VAL or -HUGE_VAL is returned (according to the sign 
of the value), and errno is set to ERANGE. 

If the correct value would cause underflow, zero is returned and errno is set to ERANGE. 

AUTHOR 

wcstod ( ) was developed by AT&T and HP. 

SEE ALSO 

wctype(3C), setlocale(3C), scanf(3S), wcstol(3C), hpnls(5), lang(5). 

STANDARDS CONFORMANCE 

wcstod():XPG4 
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NAME 

wcstol(), wcstoul() - convert wide character string to long integer 

SYNOPSIS 

ttinclude <wchar.h> 

long int wcstol (const wchar_t *nptr, wchar_t **endptr, int base); 

unsigned long int wcstoul (const wchar_t *nptr, wchar_t **endptr, int 
base) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character formatting 
functions. They parallel the 8-bit character formatting functions defined in strtol(3C). 

DESCRIPTION 

wcstol () (wcstoul ()) converts the wide character string pointed to by nptr to long int 
(unsigned long int) representation. The wide character string is scanned up to the first wide charac- 
ter inconsistent with the base. Leading "white-space" wide characters (as defined by iswspace ( ) in 
wctype(3C)) are ignored. If no conversion can take place, zero is returned. 

If base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After 
an optional leading sign, leading zeros are ignored, and Ox or OX is ignored if base is 16. 

If base is zero, the wide character string itself determines the base as follows: After an optional leading 
sign, a leading zero indicates octal conversion; a leading Ox or OX hexadecimal conversion. Otherwise, 
decimal conversion is used. 

If the value of endptr is not ( wchar_t * * ) NULL, a pointer to the wide character terminating the scan is 
returned in the location pointed to by endptr. If no integer can be formed, the location pointed to by endptr 
is set to nptr, and zero is returned. 

Definitions for these functions and the type wchar_t are provided in the <wchar . h> header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines how wide character codes are interpreted. 

International Code Set Support 

Single- and multi-byte character code sets are supported. 

RETURN VALUE 

Upon successful completion, both functions return the converted value, if any. If the correct value would 
cause overflow, wcstol ( ) returns LONG_MAX or LONG_MIN (according to the sign of the value), and 
sets errno to ERANGE; wcstoul () returns ULONG_MAX and sets errno to ERANGE. 

For all other errors, zero is returned and errno is set to indicate the error. 

ERRORS 

wcstol () and wcstoul () fail and errno is set if any of the following conditions are encountered: 

[EINVAL] The value of base is not supported. 

[ERANGE] The value to be returned would have caused overflow. 

SEE ALSO 

wctype(3C), wcstod(3C), scanf(3S). 

STANDARDS CONFORMANCE 

wcstol ():XPG4 

wcstoul ():XPG4 



I 
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NAME 

wcscat(), wcsncatO, wcscmpO, wcsncmpO, wcscpyO, wcsncpyO, wcslen(), wcschr(), wcsrchr(), wcspbrkO, 
wcsspn(), wcscspnO, wcswcs(), wcstok(), wcscoll(), wcwidth(), wcswidth() - wide character string operations 

SYNOPSIS 

#include <wchar.h> 

wchar_t *wcscat (wchar_t *wsl, const wchar_t *ws2); 

wchar_t *wcsncat (wchar_t *wsl, const wchar__t *ws2, size_t n) ; 

int wcscmp (const wchar_t *wsl, const wchar_t *ws2); 

int wcsncmp (const wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

wchar_t *wcscpy(wchar_t *wsl, const wchar_t *ws2); 

wchar_t *wcsncpy (wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

size_t wcslen(const wchar_t *ws); 

wchar_t *wcschr( const wchar_t *ws, wchar_t wc) ; 

wchar_t *wcsrchr (const wchar_t *ws, wchar_t wc); 

wchar_t *wcspbrk (const wchar_t *wsl, const wchar_t *ws2); 

size_t wcsspn(const wchar_t *wsl, const wchar_t *ws2); 

size_t wcscspn(const wchar_t *wsl, const wchar_t *ws2); 

wchar_t *wcswcs (const wchar_t *wsl, const wchar_t *ws2); 

wchar_t *wcstok(wchar_t *wsl, const wchar_t *ws2); 

int wcscoll (const wchar_t *wsl, const wchar_t *ws2); 

int wcwidth( const wchar_t wc); 

int wcswidth (const wchar_t *ws, size_t n) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character string han- 
dling functions. They parallel the 8 bit string functions defined in string(3C) . 

DESCRIPTION 

The arguments wsl, ws2, and ws point to wide character strings (arrays of type wchar_t terminated by a 
null value). 

wcscat ( ) appends a copy of wide string ws2 to the end of wide string wsl . wcsncat ( ) appends a 
maximum of n characters; fewer if ws2 is shorter than n characters. Each returns a pointer to the null- 
terminated result (the value of wsl). 

wcscmp () compares its arguments and returns an integer less than, equal to, or greater than zero, 
depending on whether wsl is lexicographically less than, equal to, or greater than ws2. The comparison of 
corresponding wide characters is done by comparing numeric values of the wide character codes. Null 
pointer values for wsl and ws2 are treated the same as pointers to empty wide strings, wcsncmp ( ) 
makes the same comparison but examines a maximum of n characters (n less than or equal to zero yields 
equality). 

wcscpy ( ) copies wide string ws2 to wsl, stopping after the null value has been copied. wcsncpyO 
copies up to n characters from ws2, adding null values to wsl if necessary, until a total of n have been 
copied. The result is not null-terminated if the length of ws2 is n or more. Each function returns wsl. 
Note that wcsncpy ( ) should not be used to copy an arbitrary structure. If that structure contains 
sizeof(wchar_t) consecutive null bytes, wcsncpyO may not copy the entire structure. Use the 
memcpyO function (see memory (3 C)) to copy arbitrary binary data. 

wcslen ( ) returns the number of wide characters in ws, not including the terminating null wide charac- 
ter. 

wcschr ( ) (wcsrchr ( ) ) returns a pointer to the first (last) occurrence of wide character wc in wide string 
ws, or a null pointer if wc does not occur in the wide string. The null wide character terminating a wide 
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string is considered to be part of the wide string. 

wcspbrk( ) returns a pointer to the first occurrence in wide string wsl of any wide character from wide 
string ws2, or a null pointer if no wide character from ws2 exists in wsl . 

wcsspn() (wcscspn( )) returns the length of the maximum initial segment of wide string wsl, which 
consists entirely of wide characters from (not from) wide string ws2. 

wcswcs ( ) returns a pointer to the first occurrence of wide string ws2 in wide string wsl, or a null pointer 
if ws2 does not occur in the wide string. If ws2 points to a wide string of zero length, wcswcs ( ) returns 
wsl. 

west ok ( ) considers the wide string wsl to consist of a sequence of zero or more text tokens separated by 
spans of one or more wide characters from the separator wide string ws2. The first call (with a non-null 
pointer wsl specified) returns a pointer to the first wide character of the first token, and writes a null wide 
character into wsl immediately following the returned token. The function keeps track of its position in the 
wide string wsl between separate calls, so that subsequent calls made with the first argument a null 
pointer work through the wide string immediately following that token. In this way subsequent calls work 
through the wide string wsl until no tokens remain. The separator wide string ws2 can be different from 
call to call. When no token remains in wsl , a null pointer is returned. 

wcscoll ( ) returns an integer greater than, equal to, or less than zero, according to whether the wide 
string pointed to by wsl is greater than, equal to, or less than the wide string pointed to by ws2. The com- 
parison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In 
the "C locale wcscoll ( ) works like wesemp ( ) . 

wcwidth ( ) returns the number of column positions required for the wide character wc, or if wc is a null 
wide character. 

weswidth ( ) returns the number of column positions required for n wide characters (or fewer than n wide 
characters if a null wide character is encountered before n wide characters are exhausted) in the wide 
string pointed to by ws. weswidth ( ) returns or if ws points to a null wide character. 

Definitions for these functions and the type wchar_t are provided in header file <wchar . h>. 

EXTERNAL INFLUENCES 
Locale 

The LC_COLLATE category determines the collation ordering used by the wcscoll ( ) function. See 
nlsinfo(l) to determine the collation used for a particular locale. 

The LC_CTYPE category determines how widths are calculated by the wcwidth ( ) and weswidth ( ) 
functions. 

WARNINGS 

The functions wescat ( ) , wesneat ( ) , wesepy ( ) , wesnepy ( ) , and westok ( ) alter the contents of 
the array to which wsl points. They do not check for overflow of the array. 

Null pointers for destination wide strings cause undefined behavior. 

Wide character movement is performed differently in different implementations, so copying that involves 
overlapping source and destination wide strings may yield unexpected results. 

For the wcscoll ( ) function, the results are undefined if the languages specified by the LC_COLLATE 
and LC_CTYPE categories use different code sets. 

AUTHOR 

west ring functions were developed by HP. 

SEE ALSO 

nlsinfo(l), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). 

STANDARDS CONFORMANCE 

wcscat():XPG4 
wcschr():XPG4 

wcscmp():XPG4 
wcscoll ():XPG4 
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wcscpy():XPG4 
wcscspn ( ) : XPG4 

wcslen():XPG4 
wcsncat():XPG4 

wcsncmp ( ) : XPG4 
wcsncpy ( } : ax"G4 

wcspbrk():XPG4 
wcsrchr():XPG4 

wcsspn():XPG4 
wcstok():XPG4 

wcswcs():XPG4 
wcswidth():XPG4 

wcwidth():XPG4 
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NAME 

iswalpha(), iswupperO, iswlower(), iswdigit(), iswxdigitO, iswalnumQ, iswspaceO, iswpunct(), iswprint(), 
iswgraph(), iswcntrl(), wctype(), iswctype() - classify wide characters 

SYNOPSIS 

#include <wchar.h> 

wctype_t wctype (const char *charclass) ; 

int iswctype (wint_t wc, wctype_t prop); 

int iswalnum(wint_t wc) 

int iswaipha (wint_t wc) 

int iswcntrl (wint_t wc) 

int iswdigit (wint_t wc) 

int iswgraph(wint_t wc) 

int iswlower (wint_t wc) 

int iswprint (wint_t wc) 

int iswpunct (wint_t wc) 

int iswspace (wint_t wc) 

int iswupper (wint_t wc) 

int iswxdigit (wint_t wc) ; 

Remarks: 

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character classification 
functions. They parallel the 8-bit character classification functions defined in ctype(3C) . 

DESCRIPTION 

These functions classify wide character values according to the rules of the coded character set identified by 
the last successful call to set locale ( ) (see setlocale(3C)). 

If set locale ( ) has not been called successfully, characters are classified according to the rules of the 
default ASCII 7-bit coded character set (see setlocale(3C)). 

Each of the classification functions is a predicate that returns non-zero for true, zero for false. 

wctype ( ) is defined for valid character class names as defined in the current locale, charclass is a string 
identifying a generic character class for which codeset-specific type information is required. The following 
class names are defined in all locales: alnum, alpha, blank, cntrl, digit, graph, lower, print, 
punct, space, upper, and xdigit. wctype ( ) returns a value of type wctype__t that can be used 
in a subsequent call to iswctype ( ) , or (wctype_t ) - 1 if charclass is not valid in the current locale. 

The classification functions return non-zero under the following circumstances, and zero otherwise: 

iswctype {wc .prop ) 

wc has the property defined by prop . 



iswaipha (wc) 
iswupper (wc) 
iswlower (wc) 
iswdigit (wc) 
iswxdigit {wc) 
iswalnum (wc) 
iswspace (wc) 

iswpunct {wc) 

iswprint (wc) 
iswgraph(wc) 



wc is a letter. 

wc is an uppercase letter. 

wc is a lowercase letter. 

wc is a decimal digit (in ASCII: characters [0-9]). 

wc is a hexadecimal digit (in ASCII: characters [0-9], [A-F] or [a-f]). 

wc is an alphanumeric (letters or digits). 

wc is a character that creates "white space" in displayed text (in ASCII: space, 
tab, carriage return, new-line, vertical tab, and form-feed). 

wc is a punctuation character (in ASCII: any printing character except the space 
character (040), digits, letters). 

wc is a printing character. 

wc is a visible character (in ASCII: printing characters, excluding the space 
character (040)). 
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iswcntrl (wc ) wc is a control character (in ASCII: character codes less than 040 and the delete 
character (0177)). 

If the argument to any of these functions is outside the domain of the function, the result is (false). 

Definitions for these functions and the types wint_t, wchar_t, and wctype_t are provided in the 
<wchar . h> header. 

EXTERNAL INFLUENCES 
Locale 

The LC_CTYPE category determines the classification of character type. 

International Code Set Support 

Single-byte character code sets are supported. Japanese HP15 and EUC multi-byte character code sets are 
supported. The classification functions return zero for values in other multi-byte character code sets out- 
side the ASCII range. 

WARNINGS 

These functions are supplied both as library functions and as macros defined in the <wchar .h> header. 
Normally, the macro versions are used. To obtain the library function, either use a #undef to remove the 
macro definition or, if compiling in ANSI-C mode, enclose the function name in parenthesis or take its 
address. The following example uses the library functions for iswalphaO, iswdigitO, and 
iswspace () : 

#include <wchar.h> 
#undef iswalpha 



main ( ) 
{ 



int (*ctype_func) ( ) ; 
if ( iswalpha (c) ) 
if ( (iswdigit) (c) ) 
ctype_func = iswspace; 



AUTHOR 

wctype ( ) was developed by AT&T and HP. 

SEE ALSO 

ctype(3C), multibyte(3C), setlocale(3C), ascii(5). 



STANDARDS CONFORMANCE 


wctype ( ) : XPG4 


is wctype () 


XPG4 


iswalnum() 


XPG4 


iswalphaO 


XPG4 


iswcntrl () 


XPG4 


iswdigitO 


XPG4 


iswgraphO 


XPG4 


iswlower () 


XPG4 


iswprint () 


XPG4 


iswpunct ( ) 


XPG4 


iswspace () 


XPG4 


iswupper O 


XPG4 



iswxdigit ( ) : XPG4 



820 - 2 - HP-UX Release 9 .0: August 1992 



wordexp(3C) wordexp(3C) 



NAME 

wordexp, wordfree - perform word expansions 

SYNOPSIS 

#inc lude < wordexp . h> 

int wordexp (const char *words, wordexp_t *pwordexp, int flags); 
void wordfree (wordexp_t *pwordexp) ; 

DESCRIPTION 

wordexp ( ) performs word expansions and places the list of expanded words into the structure pointed to 
by pwordexp . 

The words argument is a pointer to a string containing one or more words to be expanded. The expansions 
are the same as would be performed by the shell (see sh-posix(l), if words were the part of a command line 
representing the arguments to a utility. Therefore, words must not contain an unquoted new-line character 
or any of the unquoted shell special characters I , &, ;, < or >, except in the context of shell command sub- 
stitution. If words contains an unquoted comment character, #, it is treated as the beginnning of a token 
which wordexp ( ) interprets as a comment indicator, causing the remainder of words to be ignored. 

The structure type wordexp_t is defined in the header <wordexp . h>, and includes the following 
members: 

we_wor dc A s i z e_t u sed to keep count of words matched by words . 

we_wordv A char* * used as a pointer to a list of expanded words. 

we_of f s Also a size_t used to indicate number of slots to reserve at the the beginning 

of pwordexp->we_wordv . 

wordexp ( ) stores the number of generated words into pwordexp- >we_wordv. Each individual field 
created during field splitting or pathname expansion is a separated word in the pwordexp ->we_wordv 
list. The words are in order as described in shell word expansions. The first pointer after the last word 
pointer is a null pointer. 

It is the caller's responsibility to allocate the storage pointed to by pwordexp . wordexp ( ) allocates 
other space as needed, including memory pointed to by pwordexp- >we_wordv. 

wordfreeO frees any memory associated with pwordexp from a previous call to wordexp ( ) . 

The flags argument is used to control the behavior of wordexp ( ) . The value of flags is the bitwise 
inclusive OR of zero or more of the following constants, which are defined in <wordexp . h>: 

WRDE_APPEND Append words generated to the ones from a previous call to wordexp ( ) . 

WRDE_DOOFFS Make use of pwordexp- >we_offs. If this flag is set, pwordexp- 

>we_of f s is used to specify how many null pointers to add to the beginning of 
pwordexp- >we_wordv. In other words, pwordexp- >we_wordv points to 
pwordexp- >we_offs null pointers, followed by pwordexp- >we_wordc 
word pointers, followed a null pointer. 

WRDE_NOCMD Fail if command substitution is requested. 

WRDE_REUSE The pwordexp argument was passed to a previous successful call to wor- 

dexp ( ) , and has not been passed to wordfree ( ) . The result is the same as 
if the application had called wordfree ( ) and then called wordexp ( ) 
without WRDE_REUSE . 

WRDE_SHOWERR Do not redirect stderr to /dev/nul 1 . 

WRDE_UNDEP Report error on an attempt to expand an undefined shell variable. 

The WRDE_APPEND flag can be used to append a new sets of words to those generated by a previous call 
to wordexp ( ) . The following rules apply when two or more calls to wordexp ( ) are made with the 
same value of pwordexp and without intervening calls to wordfree ( ) : 

• The first such call must not set WRDE_APPEND. All subsequent calls must set it. 
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• All of the calls must set WRDE_DOOPPS, or all must not set it. 

• After the second and each subsequent call, pwordexp- >we_wordv points to a list containing 
the following: 

• Zero or more null pointers, as specified by WRED_DOOPPS and pwordexp- >we_of f s. 

• Pointers to the words that were in the pwordexp ->we_wordv list before the call, in 
the same order as before. 

• Pointers to the new words generated by the latest call, in the specified order. 

• The count returned in pwordexp->we_wordc is the total number of words from all of the calls. 

• The application can change any of the fields after a call to wordexp ( ) , but if it does so, if must reset 
them to the original value before a subsequent call, using the same pwordexp value, to wordf ree ( ) 
or wordexp ( ) with the WRDE_APPEND or WRDE_REUSE flag. 

If words contains an unquoted newline, I , &, ;,<,>, parenthesis, or curly barcket in an inappropriate con- 
text, wordexp ( ) fails, and the number of expanded words is zero. 

Unless WRDE_SHOWERR is set in flags, wordexp () redirects stderr to /dev/null for any utilities 
executed as a result of command subsitution while expanding words. If WRDE_SHOWERR is set, wor- 
dexp ( ) writes messages to stderr if syntax errors are detected while expanding words. 

If WRDE_DOOPFS is set, pwordexp- >we_offs has the same value for each wordexp ( ) call and the 
wordf ree ( ) call using a given wordexp. 

RETURN VALUE 

Upon successful completion, wordexp ( ) returns zero; otherwise, it returns a nonzero value defined in 
<wordexp .h> to indicate the error: 

WRDE_BADCHAR One of the unquoted characters I, &, ;, <, >, parentheses, or braces appears in 
words in an inappropriate context 

WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags . 

WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. 

WRDE_NOSPACE Attempt to allocate memory failed. 

WRDE_SYNTAX Shell syntax error such as unbalanced parentheses or unterminated string. 

WRDE_INTERNAL Internal error. 

If wordexp () returns the error value WRDE_NOSPACE, the pwordexp- >we_wordc and 
pwordexp- >we_wordv are updated to reflect any words that were successfully expanded. In other 
cases, they are not modified. 

SEE ALSO 

sh-posix(l), fnmatch(3C), glob(3C), regexp(5). 

STANDARDS CONFORMANCE 

wordexp ( ) : XPG4, POSIX.2 

wordf ree ( ) : XPG4, POSIX.2 
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NAME 

xdr*() - library routines for external data representation 

DESCRIPTION 

These routines allow C programmers to describe arbitrary data structures in a machine-independent 
fashion. Data for remote procedure calls are transmitted using these routines. 

Functions 

Translate arrays to/from external representation. 

Translate Booleans to/from external representation. 

Translate counted byte strings to/from external representation. 

Translate characters to/from external representation. 

Destroy XDR stream and free associated memory. 

Translate double precision to/from external representation. 

Translate enumerations to/from external representation. 

Translate floating point to/from external representation. 

Return current position in XDR stream. 

Free the memory allocated to create XDR data structures. 

Invoke the in-line routines associated with XDR stream. 

Translate integers to/from external representation. 

Translate long integers to/from external representation. 

Translate fixed-size opaque data to/from external representation. 

Similar to xdr_ref erence ( ) except it is able to follow recursive data struc- 
tures such as a binary tree. 

Chase pointers within structures. 

Change current position in XDR stream. 

Translate short integers to/from external representation. 

Translate null-terminated strings to/from external representation. 

Translate unsigned characters to/from external representation. 

Translate unsigned integers to/from external representation. 

Translate unsigned long integers to/from external representation. 

Translate unsigned short integers to/from external representation. 

Translate descriminated unions to/from external representation. 

Translate fixed-length arrays to/from external representation. 

Always return one (1). 

Package RPC routine for XDR routine, or vice-versa. 

Initialize an XDR stream. 

Initialize an XDR stream with record boundaries. 



xdr_array() 
xdr_bool ( ) 
xdr_bytes ( ) 
xdr_char ( ) 
xdr_de s t r oy ( ) 
xdr_double ( ) 
xdr_enum ( ) 
xdr_f loat () 
xdr_getpos ( ) 
xdr_f ree () 
xdr_inline() 
xdr_int ( ) 
xdr_long ( ) 
xdr_opaque ( ) 
xdr_po inter ( ) 



xdr_ref erence ( ) 
xdr_setpos ( ) 
xdr_short ( ) 
xdr_string() 
xdr_u_char ( ) 
xdr_u_int ( ) 
xdr_u_long ( ) 
xdr_u_short ( ) 
xdr_union() 
xdr_vector () 
xdr_void() 
xdr_wrapstring ( ) 
xdrmem_create ( ) 
xdrrec_create ( ) 



I 



xdrrec_endof record ( ) 

Mark XDR record stream with an end-of-record. 



xdrrec_eof ( ) 



Mark XDR record stream with an end-of-file. 



xdrrec_skiprecord ( ) 



Skip remaining record in XDR record stream. 
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xdrstdio_creat e ( ) Initialize an XDR stream as standard I/O FILE stream. 

AUTHOR 

xdr* ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

Programming and Protocols for NFS Services . 



I 
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NAME 

ypclnt(), yp_all(), yp_bind(), yp_first(), yp_get_default_domain( ), yp_master(), yp_match(), yp_next(), 
yp_order(), yp_unbind(), yperr_string(), ypprot_err() - Network Information Service client interface 

SYNOPSIS 

#include <rpcsvc/ypclnt.h> 

#include <sys/types.h> 
# include <rpc/rpc.h> 
#lnclude <rpcsvc/yp_prot .h> 

int yp_all ( 

char *indomain, 

char *inmap, 

struct ypall_callback incallback 
); 
int yp_b ind ( char * indoma in ) ; 

int yp_first( 

char * indoma in, 

char *inmap, 

char ** out key, 

int * out key 1 en, 

char **outval, 

int *outvallen 
); 

int yp_get_default_domain(char **outdomain) ; 

int yp_master( 

char * indoma in, 

char *inmap, 

char **outmaster 
); 

int yp_match( 

char * indoma in, 

char *inmap, 

char *inkey, 

int inkeylen, 

char **outval, 

int *outvallen 
); 

int yp_next( 

char *indomain, 

char *inmap, 

char *inkey, 

int inkeylen, 

char ** out key, 

int * out key 1 en, 

char **outval, h 

int *outvallen I 

); " 

int yp_order( 

char * indoma in, 

char *inmap, 

unsigned long * out order 
); 

void yp_unbind(char *indomain) ; 
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char *yperr_string(int incode) ; 

int ypprot_err (unsigned int incode); 

DESCRIPTION 

These functions provide an interface to the Network Information Service (NIS) network-lookup service. The 
package can be loaded from the library /lib/libc *a. Refer to ypfiles(4) and ypserv (1M) for an overview 
of the NIS, including the definitions of map and NIS domain, and a description of the various servers, data- 
bases, and commands comprising the NIS. 

Input parameter names begin with in; output parameter names begin with out. Output parameters of 
type char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS 
client package using malloc() and can be freed if the user code has no continuing need for it (see 
malloc(oC)). For each ouikey and outval, two extra bytes of memory are allocated at the end that contain 
new-line and null (in that order), but these two bytes are not reflected in outkeylen and outvallen. The 
indomain and inmap strings must be non-null and null-terminated. String parameters that are accom- 
panied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. 
Counted strings need not be null-terminated. 

The NIS lookup calls require a map (database) name and a NIS domain name. The client process should 
know the name of the map of interest. Client processes should obtain the host's NIS domain by calling 
yp_get_def ault_doiaain( ) and use the returned outdomain as the indomain parameter to subse- 
quent NIS calls. 

To use the NIS services, the client process must be "bound" to an NIS server that serves the appropriate NIS 
domain using yp_bind ( ) . Binding does not have to occur explicitly by user code. Rather, it occurs 
automatically whenever a NIS lookup function is called. yp__bind ( ) can be called directly for processes 
that use a backup strategy (such as a local file) when NIS services are not available. 

Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one 
socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. 
yp_unbind ( ) is available at the client interface for processes that explicitly manage their socket descrip- 
tors while accessing multiple NIS domains. The call to yp_unbind ( ) makes the NIS domain unbound 
and frees all per-process and per-node resources used to bind it. 

If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer 
then continues retrying until the operation succeeds, provided ypbind is running (see ypbindCiM)) and 
either: 

a. the client process cannot bind a server for the proper NIS domain, or 

b. RPC requests to the server fail. 

If an error is not RPC-related, if ypbind is not running, or if a bound ypserv process returns any 
answer (success or failure), the ypclnt layer returns control to the user code with either an error code or 
with a success code and any results (see ypbind (1M) and ypserv (1M)). 

Operational Behavior 

yp_match ( ) Returns the value associated with a passed key. This key must be exact; no pattern 

matching is available. 

yp_f irst ( ) Returns the first key-value pair from the named map in the named NIS domain. 

yp_next ( ) Returns the next key-value pair in a named map. To obtain the second key-value 

pair, the inkey parameter should be the outkey returned from an initial call to 
yp_first(). To obtain the (n + l)thkey-valuepair,the inkey value should be the 
outkey value from the n.th call to yp_next ( ) . 

The concepts of first and next are particular to the structure of the NIS map being pro- 
cessed. No relation in retrieval order exists to either the lexical order within any ori- 
ginal ASCII file or to any obvious numerical sorting order on the keys, values, or key- 
value pairs. The only ordering guarantee is that if the yp_first() function is 
called on a particular map and the yp_next ( ) function is called repeatedly on the 
same map at the same server until the call fails with an error of YPERRJMOMORE, 
every entry in the database is retrieved exactly once. If the same sequence of opera- 
tions is performed on the same map at the same server, the entries are retrieved in 
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the same order. 

Under conditions of heavy server load or server failure, the NIS domain may become 
unbound and bind again (perhaps to a different server) while a client is running. This 
process can cause a break in one of the enumeration (retrieval) rules: specific entries 
may be seen twice by the client or not at all. This approach protects the client from 
error messages that would otherwise be returned in the midst of the enumeration. 

yp_all ( ) describes a better solution to enumerating all entries in a map. 

yp_all () Provides a way to transfer an entire map from server to client in a single request 

using TCP (rather than UDP as with other functions in this package). The entire tran- 
saction occurs as a single RPC request and response. You can use yp_al 1 ( ) like 
any other NIS procedure by identifying the map in the normal manner and supplying 
the name of a function called to process each key-value pair within the map. A return 
from the call to yp_al 1 ( ) occurs only when the transaction is completed (either 
successfully or unsuccessfully) or the foreach function decides it does not want any 
more key-value pairs. 

The third parameter to yp_all ( ) is: 

struct ypall_callback *incallback { 

int (*foreach) (); 

char *data; 
}; 

The function foreach ( ) is called as follows: 

foreach ( 

int instatus; 

char *inkey; 

int inkeylen; 

char *inval; 

int invallen; 

char *indata; 
); 

Where: 

instatus Holds one of the return status values defined in <rpcsvc/yp_prot .h>: either 

YP_TRUE or an error code (see ypprot_err ( ) below, for a function that converts a NIS 
protocol error code to a ypclnt layer error code, as denned in <rpcsvc/ypclnt . h>). 

inkey The key and value parameters are somewhat different than defined in the SYNOPSIS sec- 

inval tion above. First, the memory pointed to by inkey and inval is private to yp_all ( ) , and 

is overwritten with the arrival of each new key-value pair. Therefore, foreach () 
should do something useful with the contents of that memory, but it does not own the 
memory. Key and value objects presented to the foreach ( ) look exactly as they do in 
the server's map. Therefore, if they were not newline-terminated or null-terminated in the 
map, they will not be terminated with newline or null characters here, either. 

indata Is the contents of the incallback->data element passed to yp_all() The dat a element 

of the callback structure can share state information between foreach ( ) and the main- 
line code. Its use is optional, and no part of the NIS client package inspects its contents. 
Cast it to something useful or ignore it as appropriate. 

The foreach ( ) function is Boolean. It should return zero to indicate it needs to be called again for 
further received key-value pairs, or non-zero to stop the flow of key-value pairs. If foreach ( ) returns a 
non-zero value, it is not called again and the functional value of yp_all ( ) is then 0. 

yp_order( ) 

Returns the order number for a map. 
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yp_master () 

Returns the host name of the master NIS server for a map. 

yperr_str ing ( ) 

Returns a pointer to an error message string that is null-terminated, but contains no period or newline. 

ypprot_err ( ) 

Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to 

yperr_string() 

RETURN VALUE 

All functions in this package of type int return if the requested operation is successful or one of the fol- 
lowing errors if the operation fails. 



[YPERR.BADARGS] 

[YPERRJBADDB] 

[YPERR.DOMAIN] 

[YPERRJCEY] 

[YPERR_MAP] 

[YPERR.NODOM] 

[YPERR_NOMORE] 

[YPERR.PMAP] 

[YPERR_RESRC] 

[YPERR.RPC] 

[YPERR.VERS] 

[YPERR.YPBIND] 

[YPERR.YPERR] 

[YPERR.YPSERV] 



args to function are bad 

NIS map is defective 

cannot bind to server on this NIS domain 

no such key in map 

no such map in server's NIS domain 

local NIS domain name not set 

no more records in map 

cannot communicate with portmap 

resource allocation failure 

RPC failure - NIS domain has been unbound 

NIS client/server version mismatch: the NIS server bound to uses Version 1 pro- 
tocol, so it does not provide yp_all ( ) functionality 

cannot communicate with ypbind 

internal NIS server or client error 

cannot communicate with ypserv 



AUTHOR 

ypclnt ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

domainname(l), rpcinfo(lM), ypserv(lM), ypfiles(4). 
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NAME 

yppasswd( ) - update user password in Network Information Service 

SYNOPSIS 

#include <pwd.h> 

# include <rpcsvc/yppasswd.h> 

lnt yppasswd(char *oldpass / struct passwd *newpw) ; 

DESCRIPTION 

If oldpass is the old, unencrypted user password, this routine replaces the password entry with the 



RPC Info 

program number: 

YPPASSWDPROG 

xdr routines: 

xdr_yppasswd(xdrs, yp) 
XDR *xdrs; 
struct yppasswd *yp; 
xdr_passwd(xdrs, pw) 
XDR *xdrs; 
struct passwd *pw; 
procs: 

YPPASSWDPROCJJPDATE 
Takes struct yppasswd as an argument; returns an integer. 
Behaves the same as the yppasswd () function. 
Uses UNDC authentication, 
versions: 

YPPASSWDVERS 

structures: 

struct yppasswd { 
char *oldpass; /* old (unencrypted) password */ 

struct passwd newpw; /* new pw structure */ 

}; 

RETURN VALUE 

yppasswdQ returns if successful and -1 if an error occurs. 

AUTHOR 

yppasswd ( ) was developed by Sun Microsystems, Inc. 

SEE ALSO 

yppasswd(l), yppasswdd(lM). 
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a641 ( ) - convert base-64 value to long integer ASCII string a64l(3C) 

AAudioString ( ) - get name of audio controller (string) passed to AOpenAudio() AAudioString(3X) 

ABestAudioAttributes ( ) - get best audio attributes for controller ABestAudioAttributes(3X) 

abort a per-process timer rmtimer(3C) 

abort ( ) - generate an IOT fault .abort(3C) 

jibs ( ) , labs ( ) - return integer absolute value abs(3C) 

absolute value, floor, ceiling, remainder, round-to-nearest functions floor(3M) 

absolute value function, complex liypot(3M) 

absolute value, return integer .abs(3C) 

ACalculateLengtiiv ) - return the size in bytes of converted data ACaiculaieLerigiii(3X) 

accelerator, math, check for presence of is_hw_j>resent(3C) 

accept ( ) - accept connection on a socket accept(2) 

access and modification times, set or update file utime(2) 

access control list (ACL), change owner and/or group in chownacl(3C) 

access control list (ACL), copy to another file cpacl(3C) 

access control list (ACL) information, get getacl(2) 

access control list (ACL) information, set setacl(2) 

access control list (ACL) structure, convert string form to strtoacl(3C) 

access control list (ACL) structure, convert to string form acltostr(3C) 

access control list; add, modify, or delete entry setaclentry(3C) 

access ( ) - determine accessibility of a file access(2) 

access exported file system information exportent(3N) 

accessibility of a file, determine .access(2) 

access fist, get group getgroups(2) 

access fist, initialize group initgroups(3C) 

access list, set group setgroups(2) 

access long integer data in a machine-independent fashion sputl(3X) 

access mode (permissions) of file, change chmod(2) 

access, open, or close a directory and associated directory stream directory(3C) 

access or build a binary search tree tsearch(3C) 

access protections, modify memory mapping mprotect(2) 

access rights to a file, get a user's effective getaccess(2) 

access utmp() orwtmpO file getut(3C) 

accounting: enable or disable process accounting acct(2) 

acct ( ) - enable or disable process accounting acct(2) 

ACheckEvent ( ) - get first event found in audio event queue ACheckEvent(3X) 

ACheckMaskEvent ( ) - get first event in audio event queue that matches mask ACheckMaskEvent(3X) 

AChooseAFileAttributes ( ) - select attributes for creating new file AChooseAFileAttributes(3X) 

AChoosePlayAttributes ( ) - select attributes for playing existing file ACh.oosePlayAttributes(3X) 

AChooseSourceAttributes ( ) - select attributes for existing file or stream ... AChooseSourceAttributes(3X) 

aclentrystart ( ) - convert pattern string form to access control list (ACL) structure strtoacl(3C) 

ACloseAudioO -close connection to specific audio server ACloseAudio(3X) 

acltostr ( ) - convert access control fist (ACL) structure to string form acltostr(3C) 

AConnectionNumberO -get audio server connection number AConnectionNumber(3X) 

AConnectRecordStreamO - connect socket to TCP socket address AConnectRecordStream(3X) 

AConvertAFile ( ) - convert audio file data format AConvertAFile(3X) 

AConvertBufferO - convert a buffer of data AConvertBuffer(3X) 

acosdf ( ) - trigonometric arcosine function (float, degrees) trigd(3M) 

acosdO - trigonometric arcosine function (degrees) trigd(3M) 

acosf ( ) - trigonometric arcosine function (float) trig(3M) 

acos ( ) - trigonometric arcosine function trig(3M) 

acquire exclusive use of audio server AGrabServer(3X) 

ACreateSBucket ( ) - create empty sound bucket and return pointer to it ACreateSBucket(3X) 

active controllers on HP-IB, change hpib_pass_ctl(3l) 

activity on specified HP-IB bus, stop Jipib_abort(3l) 

ADataFormats ( ) - get list of data formats supported by audio controller ADataFormats(3X) 

add argument and data to NetlPC option buffer addopt(3N) 

add a swap device for interleaved paging/swapping swapon(2) 

add audio event handler for this connection AtInitialize(3X) 

Index: Volume 2 831 



Index 
Volume 2 

Description Entry Name(Section) 

add callback procedure for audio toolkit AtAddCallback(3X) 

addexportent ( ) - access exported file system information exportent(3N) 

addmntent ( ) - add entry to open file system description file getmntent(3X) 

add, modify, or delete access control list entry setaclentry(3C) 

addopt ( ) - add argument and data to NetlPC option buffer addopt(3N) 

addresses - first locations beyond allocated program regions end(3C) 

address, get socket getsockname(2) 

address manipulation routines, Internet inet(3N) 

address of connected peer, get getpeername(2) 

address string conversion routines, network station net_aton(3C) 

address to a socket, bind hind(2) 

add value to environment .putenv(3C) 

ADestroySBucket ( ) - destroy specified sound bucket ADestroySBucket(3X) 

advance () - advance pointer to next 8- or 16-bit character nl_tools_16(3C) 

advance ( ) - regular expression substring comparison routines regexp(3X) 

advise system of process' expected paging behavior madvise(2) 

AEndC Olivers ion ( ) - finish stream data conversion AEndConversion(3X) 

AE vents Queued ( ) - get number of events in queue for server connection AEventsQueued(3X) 

AGetAFileAt tributes ( ) - get file attributes of file AGetAFileAttributes(3X) 

AGetChannelGain- get transaction channel gain AGetChannelGain(3X) 

AGetDataFormats ( ) - get data formats for specified file format AGetDataFormats(3X) 

AGetErrorText ( ) - copy error description into specified buffer AGetErrorText(3X) 

AGetGainO - get play volume or record gain of specified transaction AGetGain(3X) 

AGetSBucketData ( ) - copy data in sound bucket to buffer AGetSBucketData(3X) 

AGetSilenceValue ( ) - get a silence value AGetSilenceValue(3X) 

AGetSystemChannelGain ( ) - get system or monitor channel gain AGetSystemChannelGain(3X) 

AGetTransStatusO - get status of specified transaction AGetTransStatus(3X) 

AGMGainRestricted ( ) - find out if audio controller restricts gain entries AGMGainRestricted(3X) 

AGrabServer ( ) - acquire exclusive use of audio server AGrabServer(3X) 

AInputChannels ( ) - get list of A/D input channels on current hardware AInputChannels(3X) 

Alnputsources ( ) - get types of input sources existing on current hardware AInputSources(3X) 

alarm clock, set a process's alarm(2) 

alarm ( ) - set a process's alarm clock alarm(2) 

allocate a per-process timer jnktimer(3C) 

allocate data and stack space then lock process into memory datalock(3C) 

allocated program regions, first locations beyond end(3C) 

allocation, change data segment space brk(2) 

allocator for main memory jnalloc(3C) 

allow interface to enable SRQ line on HP-IB hpib_rqst_srvce(3l) 

almanac () - return numeric date information in MPE format almanac(3X) 

ALoadAFile ( ) - copy audio file into new sound bucket with data conversion ALoadAFile(3X) 

alphasort ( ) - sort a directory pointer array scandir(3C) 

AMaskEvent ( ) - get first matching event in audio event queue AMaskEvent(3X) 

AMaxlnputGain ( ) - get maximum input gain supported by audio controller AMaxInputGain(3X) 

AMaxOutputGain ( ) - get maximum output gain supported by audio controller AMaxOutputGain(3X) 

AMinlnputGain ( ) - get minimum input gain supported by audio controller AMinInputGain(3X) 

AMinOutputGain ( ) - get minimum output gain supported by audio controller AMinOutputGain(3X) 

ANextEvent ( ) - dequeue and return first event in audio event queue ANextEvent(3X) 

anonymous memory region, initialize semaphore in mapped file or msem_init(2) 

anonymous region, remove semaphore in mapped file or msem_remove(2) 

another process, request connection to ipcconnect(2) 

ANumDataFormats ( ) - get number of data formats supported by controller ANumDataFormats(3X) 

ANumSamplingRates ( ) - get number of sampling rates supported by controller ANumSamplingRates(3X) 

AOpenAudioO - open connection to specified audio server AOpenAudio(3X) 

AOutput Channels ( ) - get D/A output channels existing on current hardware AOutputChannels(3X) 

AOutputDestinat ions ( ) - get types of output destinations on hardware AOutputDestinations(3X) 

APauseAudioO - pause the specified audio transaction APauseAudio(3X) 

APeekEvent ( ) - return but do not dequeue first event in audio event queue APeekEvent(3X) 
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APlaySBucket ( ) - play specified sound bucket and return transaction ID APlaySBucket(3X) 

APlaySStream( ) - initiate transaction and return transaction ID and SStream structure .. APlaySStream(3X) 

AProtocolRevision ( ) - get revision number of protocol on audio server AProtocolRevision(SX) 

AProtocolVersion( ) - get version number of protocol on audio server AProtocolVersion(SX) 

APutBackBvent ( ) - push event onto head of audio event queue APutBackEvent(SX) 

APutSBucketData ( ) - copy audio data from buffer to sound bucket APutSBucketData(SX) 

AQLength ( ) - return number of events on audio event queue AQLength(3X) 

AQueryAPila ( ) -get file format of specified file AQueryAFile(3X) 

arcsine, arccosine, arctangent trigonometric functions trig(3M) 

arcsine, arccosine, arctangent trigonometric functions (degrees) trigd(3M) 

ARecordAData ( ) - read audio data into sound bucket ARecordAData(3X) 

ARecordSStream( ) - initiate transaction ARecordSStream(3X) 

AResumeAudioO - resume specified audio transaction AResumeAudio(3X) 

argument and data to NetlPC option buffer, add addopt(3N) 

argument list, print formatted output of a varargs vprintf(3S) 

argument, varargs, formatted input conversion to a vscanf(3S) 

argument vector, get option letter from getopt(3C) 

arm a per-process timer, relatively xeltimer(3C) 

array element, convert floating-point number to string or string ecvt(3C) 

array, sort a directory pointer scandir(3C) 

ASamplingRates ( ) - return list of sampling rates supported by audio controller ASamplingRates(3X) 

ASaveSBucket ( ) - write sound bucket data into file with data conversion ASaveSBucket(3X) 

ASCII, 7-bit, translate characters to .conv(3C) 

ASCII string, convert between long integer and base-64 a64l(3C) 

ASCII string, convert long integer to ltostr(3C) 

asctime ( ) , nl_ascxtirae ( ) - convert tm structure date and time to string ctime(3C) 

ASelect Input () -request report of specified audio events ASelectInput(3X) 

AServerVendor ( ) - get vendor name of audio server for this connection AServerVendor(3X) 

ASetChannelOain ( ) - set transaction channel gain ASetChannelGain(3X) 

ASetCloseDownMode ( ) - set close-down mode on connection ASetCloseDownMode(3X) 

ASetErrorHandler ( ) -replace audio error handler ASetErrorHandler(3X) 

ASet6ain( ) - set play volume or record gain of specified transaction ASetGain(3X) 

ASetlOErrorHandlerO -replace audio I/O error handler ASetIOErrorHandler(3X) 

ASetSystemChannelGain( ) - set system or monitor channel gain ASetSystemChannelGain(3X) 

ASetSystemPlayGainO - set system play volume ASetSystemPlayGain(3X) 

ASetSystemRecordGainO - set system record gain ASetSystemRecordGain(3X) 

ASetupConversion( ) - perform setup required for stream data conversion ASet up Conversion (3X) 

ASimplePlayer ( ) - return gain matrix of basic play device ASimplePlayer(3X) 

ASimpleRecorder ( ) - return gain matrix of basic recording device ASimpleRecorder(3X) 

asindf ( ) - trigonometric arcsine function (float, degrees) trigd(3M) 

asindO - trigonometric arcsine function (degrees) trigd(3M) 

asinf ( ) - trigonometric arcsine function (float) •. trig(3M) 

asinh( ) - inverse hyperbolic sine function asinh(3M) 

asin( ) - trigonometric arcsine function trig(3M) 

ASoundBitOrder ( ) - get bit order used for one-bit-per-sample data ASoundBitQrder(3X) 

ASoundByteOrder ( ) - get audio data byte order for this connection ASoundByteQrder(3X) 

assertion, verify program assert(3X) 

assert ( ) - verify program assertion .assert(3X) 

assign buffering to a stream file setbuf (3S) 

associate name with call socket or destination call socket ipcname(2) 

AStopAudio ( ) - stop specified audio transaction AStopAudio(3X) 

async_daemon: NFS daemon jnfssvc(2) 

asynchronous faults, enable pfm_$enable(3) 

asynchronous faults, enable .pfm_$enable_faults(3) 

asynchronous faults, inhibit but allow time-shced task switching pfm_$inliibit_faults(3) 

asynchronous faults, inhibit ". pfm_$inhibit(3) 

AtAddCallback ( ) - add callback procedure for audio toolkit AtAddCallback(3X) 

atan2df ( ) - trigonometric arctangent-and-quadrant function (float, degrees) ...trigd(3M) 
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atan2d( ) - trigonometric arctangent-and-quadrant function (degrees) trigd(3M) 

atan2f ( ) - trigonometric arctangent-and-quadrant function (float) trig(3M) 

atan2 ( ) -trigonometric arctangent-and-quadrant function trig(3M) 

atandf ( ) - trigonometric arctangent function (float, degrees) trigd(3M) 

atand( ) — trigonometric arctangent function (degrees) iri«*d(3M) 

atanf ( ) - trigonometric arctangent function (float) trig(3M) 

atan() - trigonometric arctangent function trig(3M) 

atexit ( ) - register a function to be called at program termination atexit(2) 

Atlnitialize ( ) - add audio event handler for this connection AtInitialize(3X) 

ATN commands, enable/disable odd parity on hpib_j>arity_ctl(3l) 

afcof ( ) — convert string to double-t>recision number strtod(3C) 

atoi ( ) - convert string to long integer strtol(3C) 

atol ( ) - convert string to long integer strtol(3C) 

atomically release blocked signals and wait for interrupt sigpause(2) 

AtRemoveCallback ( ) - set callback to NULL ...AtRemoveCallback(3X) 

attach shared memory to data segment shmop(2) 

Attention line on HP-IB, control Jipib_atn_ctl(3l) 

attributes of specified file, get file AGetAFileAttributes(3X) 

attributes to use when creating a new file, select AChoosePlayAttributes(3X) 

AuCreatePlayO - create an audio play widget AuCreatePlay(3X) 

AuCreateRecordO - create an audio record widget AuCreateRecord(3X) 

audctl ( ) - start or halt auditing system; set or get audit files audctl(2) 

audiochannel gain, get system or monitor AGetSystemChannelGain(3X) 

audio channel gain, set system or monitor ASetSystemChannelGain(3X) 

audio event handler for this connection, add .AtInitialize(3X) 

audio file data format, convert AConvertAFile(3X) 

audio play widget AuPlayWidget(3X) 

audio play widget, create an AuCreatePlay(SX) 

audio record widget AuRecordWidget(3X) 

audio record widget, create an AuCreateRecord(3X) 

audio toolkit, add callback procedure for AtAddCallback(3X) 

audio widget play operation, initiate an AuInvokePlay(3X) 

audio widget record operation, initiate an AuInvokeRecord(3X) 

audit: get events and system calls currently being audited getevent(2) 

audit: set current events and system calls to be audited setevent(2) 

audit: set or clear auditing on calling process setaudproc(2) 

audit: set or get audit files audctl(2) 

audit: start or halt auditing system .audctl(2) 

audit files, set or get 4 audctl(2) 

audit ID (aid( ) ) for current process, get getaudid(2) 

audit ID (aid()), set for current process setaudid(2) 

auditing, set or clear on calUng process setaudproc(2) 

auditing, suspend or resume on current process audswitch(2) 

auditing system, start or halt .audctl(2) 

audit process flag for calling process, get getaudproc(2) 

audit record, write for self-auditing process audwrite(2) 

audswitchO - suspend or resume auditing on current process audswitch(2) 

audwrite ( ) - write audit record for self-auditing process audwrite(2) 

AulnvokePlay ( ) - initiate an audio widget play operation AuInvokePlay(3X) 

AulnvokeRecord ( ) - initiate an audio widget record operation AuInvokeRecord(3X) 

AUngrabServer ( ) - release server from exclusive use by this connection AUngrabServer(3X) 

AUpdateBataLength( ) -update a file's header AUpdateDataLength(3X) 

AuPlayWidget ( ) - audio play widget AuPlayWidget(3X) 

AuRecordWidget ( ) - audio record widget AuRecordWidget(3X) 

AuSaveFile ( ) - save sound bucket data created by record widget AuSaveFile(3X) 

auth_destroy() - destroy authentication information handle rpc(3C) 

autlmone_create ( ) - get RPC authentication handle with no checking rpc(3C) 

authunix_create_def ault ( ) - get default UNIX authentication handle rpc(3C) 
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authunix_create ( ) - get RPC authentication handle with UNIX permissions rpc(3C) 

AVendorRelease ( ) - get vendor release number of audio server for this connection AVendorRelease(3X) 

AWriteAHeader ( ) - write a header for an audio file AWriteAHeader(3X) 

back into input stream, push character ungetc(3S) 

back into input stream, push wide character ungetwc(3C) 

base-64 ASCII string, convert long integer to a64l(3C) 

baud rate, tty, set or get .cfspeed(3C) 

bcmp ( ) - BSD memory compare memory(3C) 

bcopyO -BSD memory copy jnemory(3C) 

behavior, advise system of process' expected paging madvise(2) 

Bessel functions Jbessel(3M) 

binary input/output to a stream file, buffered fread(3S) 

binary search routine for sorted tables bsearch(3C) 

binary search tree, manage a .tsearch(3C) 

bind a socket to a privileged IP port bindresvport(3N) 

bind() -bind address to a socket .bind(2) 

bindresvport ( ) - bind a socket to a privileged IP port bindresvport(3N) 

blclose( ) - terminal block-mode library interface blmode(3C) 

blget ( ) - terminal block-mode library interface blmode(3C) 

blmode ( ) - terminal block-mode library interface blmode(3C) 

blocked signals, examine and change sigprocmask(2) 

blocked signals, release and atomically wait for interrupt sigpause(2) 

block-mode terminal I/O library interface blmode(3C) 

block signals sigblock(2) 

blopen( ) - terminal block-mode library interface blmode(3C) 

blread( ) - terminal block-mode library interface blmode(3C) 

blset ( ) - terminal block-mode library interface blmode(3C) 

boot the system reboot(2) 

break value and file size limits, get or set ulimit(2) 

brk(), sbrk() -change data segment space allocation brk(2) 

BSD-4.2-compatible kill ( ) , sigvec ( ) , and signal ( ) system calls bsdproc(2) 

bsearchO -binary search routine for sorted tables bsearch(3C) 

buffer, add argument and data to NetlPC option addopt(3N) 

buffered binary input/output to a stream file fread(3S) 

buffered input/output standard stream file package stdio(3S) 

buffer, flush with or without closing stream fclose(3S) 

buffering, assign to a stream file .setbuf(3S) 

buffer, initialize NetlPC option initopt(3N) 

buffer, obtain option code and data from NetlPC option readopt(3N) 

buffers, flush to disk sync(2) 

buffers, use to perform I/O with an HP-IB channel hpib_io(3l) 

build or access a binary search tree tsearch(3C) 

bus address for an interface, set HP-IB hpib_address_ctl(3l) 

bus see HP-IB 

bus, stop activity on specified HP-IB Jipib_abort(3l) 

byte order, network and host, convert values between byteorder(3N) 

bytes needed by a NetlPC option, return number of optoverhead(3N) 

bytes over HP-IB, send command hpib_send_cmnd(3l) 

bytes, swap swab(3C) 

byte_status ( ) , byte_status ( ) - test for valid 1- or 2-byte character nl_tools_16(3C) 

bzero ( ) - BSD memory clear jnemory(3C) 

cabs ( ) - complex absolute value function hypot(3M) 

cachectl ( ) - flush and/or purge the cache cachectl(3C) 

cache, flush and/or purge the .cachectl(3C) 

calendar ( ) - return MPE calendar date calendar(3X) 

callback procedure for audio toolkit, add AtAddCallback(3X) 

callback to NULL, set AtRemoveCallback(3X) 

calling process, get audit process flag for getaudproc(2) 
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calling process, set or clear auditing on setaudproc(2) 

calling process, signal the pfm_$signal(3) 

calloc ( ) - allocate memory for array - main memory allocator malloc(3C) 

callrpc ( ) - call remote procedure jrpc(3C) 

call socket or destination call socket, associate name with .......... ,....,........„,ipcname(2) 

call socket or destination call socket, delete name associated with a ipcnamerase(2) 

call socket or VC socket, determine status of ipcselect(2) 

call socket, receive connection request on a ipcrecvcn(2) 

calls, remote procedure, library routines for jrpc(3C) 

calls, system, BSD-4.2-compatible kill ( ) , slgvec ( ) , and signal ( ) bsdproc(2) 

cancel a per-process timer „.,„,. ,„.,..,..,.,,,,,„,,„„,,„„,,„„„„„„,„, „„„„amtimer(3C) 

C and Pascal execution startup routines .crt0(3) 

capabilities, check for presence of hardware is_hwjpresent(3C) 

catalog for reading, close or openNLS message catopen(3C) 

catalog support, RTE/MPE-style message catread(3C) 

catalogue, get message from an NLS message catgetmsg(3C) 

catclose ( ) - close NLS message catalog for reading catopen(3C) 

catgetmsg ( ) - get message from an NLS message catalogue catgetmsg(3C) 

catgets ( ) - get an NLS program message catgets(3C) 

catopen( ) - open NLS message catalog for reading catopen(3C) 

catreadO - MPE/RTE-style message catalog support catread(3C) 

cbrtf (), cbrt(), sqrt(), sqrtf () - cube root, square root functions exp(3M) 

cbrt ( ) , sqrt ( ) , sqrtf ( ) , cbrtf ( ) - cube root, square root functions exp(3M) 

c_colwidth ( ) , c_colwidth () - test for valid first byte in 16-bit character nl_tools_16(3C) 

ceil ( ) , floor ( ) , f mod ( ) , f modf ( ) , f abs ( ) , 

f absf ( ) , rint ( ) - ceiling, floor, remainder, absolute value, round-to-nearest functions floor(3M) 

ceiling, floor, remainder, absolute value, round-to-nearest functions floor(3M) 

cfgetispeedO - get tty input baud rate cfspeed(3C) 

cf getospeed ( ) - get tty output baud rate cfspeed(3C) 

cf setispeed( ) - set tty input baud rate cfspeed(3C) 

cfsetospeedO - set tty output baud rate cfspeed(3C) 

change access mode (permissions) of file chmod(2) 

change active controllers on HP-IB Jipibjpass_ctl(3l) 

change data segment space allocation .brk(2) 

change or add value to environment .putenv(3C) 

change or examine blocked signals sigprocmask(2) 

change or examine signal action sigaction(2) 

change or read real-time priority rtprio(2) 

change owner and group of a file .chown(2) 

change owner and/or group in access control list (ACL) chownacl(3C) 

change priority of a process nice(2) 

change root directory jchroot(2) 

change the name of a file rename(2) 

change working directory jchdir(2) 

channel, create an interprocess pipe(2) 

channel from buflFers, perform I/O with an HP-IB hpib_io(3l) 

channel gain, get system or monitor audio AGetSystemChannelGain(3X) 

channel gain, get transaction AGetChannelGain(3X) 

channel gain, set system or monitor audio ASetSystemChannelGain(3X) 

channel gain, set transaction ASetChannelGain(3X) 

channel, perform low-overhead I/O on an HP-IB/GPIO/parallel io_burst(3l) 

character back into input stream, push ungetc(3S) 

character code set, convert to another iconv(3C) 

character, compare memory contents with specified memory(3C) 

character device special file, control ioctl(2) 

character, find location of in memory memory(3C) 

character or data word from a stream file, get getc(3S) 

character or word, put on a stream putc(3S) 
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characters and strings conversions, multibyte multibyte(3C 

characters, classify according to type .ctype(3C 

characters, classify according to type wctype(3C 

characters, classify for use with NLS nl_ctype(3C 

character, set contents of memory area to specified memory(3C 

characters, tools to process 16-bit nl_tools_16(3C 

characters, translate for use with NLS (obsolete - useconv(3C)) nl_conv(3C 

characters, translate to uppercase, lowercase, or 7-bit ASCII conv(3C 

character-string login name of the user, get cuserid(3S' 

character string operations string(3C 

character string or stream file, read from with formatted input conversion scanf(3S 

CH&RADVO - get character and advance pointer to next character nl_tools_16(3C 

charato - get value of 8- or 16-bit character nl_tools_16(3C 

chdir ( ) - change working directory .chdir(2 

check for presence of hardware capabilities is_hw_present(3C 

check the network, scatter data to spray(3N) 

child or traced process to stop or terminate, wait for wait(2' 

child process and process times, get .times(2 

chmodO, fchmodO -change access mode (permissions) of file chmod(2 

chownacl ( ) - change owner and/or group in access control list (ACL) chownacl(3C 

chownO, fchownO - change owner and group of a file ....chown(2 

chroot ( ) - change root directory .chroot(2| 

circuit connection, establish or receive data on NetlPC virtual ipcrecv(2' 

circuit connection, send data on a virtual ipasend(2 

classify characters according to type .ctype(3C 

classify characters according to type wctype(3C 

classify characters for use with NLS nl_ctype(3C 

cleanup handler, establish a .pfm_$cleanup(3 

cleanup handler, release a .pfm_$rls_cleanup(3^ 

cleanup handler, reset a .pfm_$reset_cleanup(3 

cleanup handlers, exiting pfm_$signal(3' 

cleanup handlers pfm_$intro(3 

clearenv - clear the process environment clearenv(3C 

clearerr ( ) - clear I/O error on stream ferror(3& 

clear or set auditing on calling process setaudproc(2 

clear the process environment .clearenv(3C 

client interface, Network Information Service ypclnt(3C 

clnt_broadcast ( ) - broadcast remote procedure call everywhere rpc(3C 

clnt_call ( ) - call remote procedure associated with client handle rpc(3C 

clnt_control ( ) - change or retrieve information associated with client handle rpc(3C 

clnt_create ( ) - create RPC client using caller-specified transport rpc(3C 

clnt_destroy ( ) - destroy client's RPC handle rpc(3C 

clnt_f reeres ( ) - free data allocated by RPC/XDR when decoding results rpc(3C 

clnt_geterr ( ) - copy error info from client handle to error structure rpc(3C 

clnt_pcreateerror ( ) - print reason why client handle creation failed rpc(3C 

clnt_perrno ( ) - print message corresponding to condition given rpc(3C 

clnt_perror ( ) - print message explaining why RPC call failed rpc(3C 

clntraw_create ( ) - create toy RPC client for simulation .....rpc(3C 

clnt_spcreateerror ( ) - get pointer to why client handle creation failed rpc(3C 

clnt_sperrno ( ) -get pointer to message corresponding to error value rpc(3C 

clnt_sperror ( ) - get pointer to why an RPC call failed rpc(3C 

clnttcp_create ( ) -create RPC client using TCP transport rpc(3C 

clntudp_create ( ) - create RPC client using UDP transport rpc(3C 

clock date and time, get or set system gettimeofday(2 

clock, get current value of system- wide getclock(3C 

clock ( ) - report CPU time used , .clock(3C 

clock () - return the MPE clock value clock(3X' 

clock, set value of system-wide .setclock(3C 

Index: Volume 2 837 



Index 

Volume 2 

Description Entry Name(Section) 

clock value, MPE, return the .clock(3X) 

close, access, or open a directory and associated directory stream directory(3C) 

close a stream fclose(3S) 

close ( ) - close a file descriptor .elose(2) 

close connection to specific audio server ACIoseAudio(3X) 

closedir ( ) - close a currently open directory directory(3C) 

close legal user shells file .getusershell(3C) 

closelog ( ) - close system log file syslog(3C) 

close or open NLS message catalog for reading catopen(3C) 

close or open pipe I/O to or from a process .popen(3S) 

cluster configuration file, get entry from getccent(3C) 

cluster nodes, get a fist of active diskless cnodes(2) 

clusters, diskless .see diskless clusters 

cnodeid ( ) - get diskless cnode ID of local machine cnodeid(2) 

cnode ID of local machine, get diskless cnodeid(2) 

cnodes —get a list of active nodes in cluster cnodes(2) 

code set conversion, character iconv(3C) 

collation, non-ASCII string jal_string(3C) 

command bytes over HP-IB, send hpib_send_cmnd(3l) 

command, remote, return a stream to j*cmd(3N) 

command, return stream to a remote xexec(3N) 

command, shell, issue a system(3S) 

communication, create an endpoint for .socket(2) 

communication package, standard interprocess stdipc(3C) 

compare contents of memory with character memory(3C) 

compare two non-ASCII strings nl_string(3C) 

compare two strings string(3C) 

compare two wide strings .wcstring(3C) 

comparison routines for regular expressions regexp(3X) 

compile and match routines for regular expressions regexp(3X) 

compile a regular expression regcmp(3X) 

compile ( ) - regular expression compile routine regexp(3X) 

compiling routines, regular expression jregcomp(3C) 

complementary error function and error function erf(3M) 

completion status code, return an error message for a error_$c_text(3) 

complex absolute value function Jiypot(3M) 

concatenate two strings string(3C) 

concatenate two wide strings .wcstring(3C) 

condition becomes true, wait until the requested status hpib_status_wait(3I) 

conditions, define for I/O device interrupt io_on_interrupt(3l) 

conduct a serial poll on HP-IB Jipib_spoll(3l) 

conduct parallel poll on HP-IB Jipibjppoll(3l) 

configurable pathname variables, get .pathconf(2) 

configurable system variables, get sysconf(2) 

configuration file, cluster, get entry from getccent(3C) 

configuration values, get string-valued confstr(3C) 

conf str ( ) - get string-valued configuration values confstr(3C) 

connected peer, get address of getpeername(2) 

connected sockets, create a pair of socketpair(2) 

connect ( ) - initiate connection on a socket connect(2) 

connection, add audio event handler for this AtInitialize(3X) 

connection, establish an out-bound terminal line dial(3C) 

connection, establish or receive data on NetlPC virtual circuit ipcrecv(2) 

connection on a socket, accept .accept(2) 

connection on a socket, initiate .connect(2) 

connection request on a call socket, receive ipcrecvcn(2) 

connection, send data on a virtual circuit ipcsend(2) 

connections on a socket, listen for listen(2) 
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connection to another process, request ipcconnect(2) 

connect socket to TCP socket address; return transaction ID AConnectRecordStream(3X) 

consumption limit, get or set system resource getrlimit(2) 

context-dependent file path names, manipulate getcdf(3C) 

context-dependent file search, return process context for getcontext(2) 

context, signal stack, set and/or get sigstack(2) 

control Attention line on HP-IB ±ipib_atn_ctl(3l) 

control character device special file ioctl(2) 

control DMA allocation for an interface io_dma_ctI(3l) 

control EOI mode for HP-IB file Jbpib_eoi_ctl(3l) 

control, file system fsctl(2) 

control functions, tty line .tccontrol(3C) 

controllers on HP-IB, change active hpib_pass_ctl(3l) 

control fines on GPIO card, set gpio_set_ctl(3l) 

controlling terminal, generate file name of ctermid(3S) 

control operations, message mstctl(2) 

control operations, semaphore .semctl(2) 

control operations, shared memory shmctl(2) 

control register defaults (floating-point), set fpgetround(3M) 

control register (floating-point), examine and set fpgetround(3M) 

control response to parallel poll on HP-IB hpib_card_ppoll_resp(3I) 

control routines for open-files fcntl(2) 

control system log syslog(3C) 

control system resource consumption limit getrlimit(2) 

control terminal device (Version 6 compatibility only) stty(2) 

control the HP-IB interface Remote Enable line hpib_ren_ctl(3l) 

control tty device .tcattribute(3C) 

conventions, numeric formatting, of current locale, query localeconv(3C) 

conversion, formatted input, to a varargs argument vscanf(3S) 

conversion routines, network station address string net_aton(3C) 

conversions, multibyte characters and strings multibyte(3C) 

convert a buffer of data AConvertBuffer(3X) 

convert access control list (ACL) structure to string form acltostr(3C) 

convert audio file data format AConvertAFile(3X) 

convert between 3-byte integers and long integers 13tol(3C) 

convert between long integer and base-64 ASCII string a64l(3C) 

convert character code set to another iconv(3C) 

convert date and time to string ctime(3C) 

convert date and time to string .strftime(3C) 

convert date and time to wide-character string wcsftime(3C) 

convert file to stream fopen(3S) 

convert floating-point number to string or string array element ecvt(3C) 

convert long double floating-point number to string ldcvt(3C) 

convert long integer to string ltostr(3C) 

convert string data order strord(3C) 

convert string form to access control list (ACL) structure strtoacl(3C) 

convert string to double-precision number strtod(3C) 

convert string to floating-point number cvtnum(3C) 

convert string to long double-precision number strtold(3C) 

convert user format date and time .getdate(3C) 

convert values between host and network byte order byteorder(3N) 

convert wide character string to double-precision number wcstod(3C) 

coprocessor, math, check for presence of is_hwjpresent(3C) 

copy access control fist (ACL) to another file cpacl(3C) 

copy audio data from buffer to sound bucket APutSBucketData(3X) 

copy audio data in sound bucket to buffer; return number of bytes AGetSBucketData(3X) 

copy audio file into new sound bucket with data conversion ALoadAFile(3X) 

copy error description into specified buffer AGetErrorText(3X) 

Index: Volume 2 839 



Index 

Volume 2 

Description Entry Name(Section) 

copy memory to another area jnemory(3C) 

copysign ( ) , copysignf ( ) - copysign functions ieee(3M) 

copysignf ( ) , copysign ( ) - copysign functions ieee(3M) 

copysign functions ieee(3M) 

cosdf ( ) - trigonometric cosine function (float, degrees) trigd(3M) 

cosd ( ) - trigonometric cosine function (degrees) trigd(3M) 

cosf ( ) - trigonometric cosine function (float) trig(3M) 

cosh ( ) , coshf ( ) - hyperbolic cosine functions sinh(3M) 

coshf ( ) , cosh{ ) - hyperbolic cosine functions sinh(3M) 

cosh ( ) - inverse hyperbolic cosine function asinh(3M) 

cosine trigonometric function (degrees) ....,.,„,„„...„,..,.........,..... trigd(SM) 

cosine trigonometric function .trig(3M) 

cos ( ) - trigonometric cosine function trig(3M) 

cpacl ( ) - copy access control list (ACL) to another file cpacl(3C) 

cpu, set name of host sethostname(2) 

CPU, set NetlPC node name of host ipcsetnodename(2) 

CPU time used, report clock (3 C) 

creat ( ) - create a new file or rewrite an existing one creat(2) 

create a call socket ipccreate(2) 

create a destination descriptor ipcdest(2) 

create a directory file .mkdir(2) 

create a directory, or a special or ordinary file mknod(2) 

create a name for a temporary file tmpnam(3S) 

create an audio play widget AuCreatePlay(3X) 

create an audio record widget AuCreateRecord(3X) 

create an endpoint for communication socket(2) 

create a new file creat (2) 

create a new file or rewrite an existing one creat(2) 

create a new process £ork(2) 

create an interprocess channel pipe (2) 

create a pair of connected sockets .socketpair(2) 

create a socket socket(2) 

create a temporary file .tmpfile(3S) 

create a unique (usually temporary) file name mktemp(3C) 

created by record widget, save sound bucket data AuSaveFile(3X) 

create empty sound bucket and return pointer to it ACreateSBucket(3X) 

create filenames glob(3C) 

create session and set process group ID .setsid(2) 

creating a new file, select play attributes to use when AChoosePlayAttributes(3X) 

crtO .o, gcrtO .o, mcrtO .o, f rtO .o, mf rtO .o - execution startup routines crt0(3) 

crtO .o, mcrtO . o - C and Pascal execution startup routines crt0(3) 

CRT optimization and screen handling package curses(3X) 

CRT screen handling and optimization package curses(3X) 

crypto, setkeyO, encrypt () - generate hashing encryption crypt(3C) 

ctermid ( ) - generate file name for terminal ctermid(3S) 

ctime(), nl_cxtime ( ) -convert clock () date and time to string ctime(3C) 

cube root, square root, power, logarithm, exponential functions esp(3M) 

current events and system calls to be audited setevent(2) 

current host, get name of gethostname(2) 

current HP-UX system, get name and version of uname(2) 

current locale, query numeric formatting conventions of localeconv(3C) 

current process, get audit ID (aidO)for getaudid(2) 

current process, set audit ID (aidO)for setaudid(2) 

current process, suspend or resume auditing on audswitch(2) 

current User, find the slot in the utmp ( ) file of the ttyslot(3C) 

current value of system-wide clock, get getclock(3C) 

current working directory, get path-name of getcwd(3C) 

currlangidO -get current NLS language ID number langinfo(3C) 
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curses ( ) - CRT screen handling and optimization package curses(3X) 

cursor control, CRT optimization, and screen handling package curses(3X) 

cu8erid() -get character-string login name of the user cuserid(3S) 

cvtnum( ) - convert string to floating-point number cvtnum(3C) 

daemons, NFS nfssvc(2) 

data and stack space, allocate then lock process into memory datalock(3C) 

database operations, error text error_$intro(3) 

database subroutines (new multiple database version) ndbm(3X) 

database subroutines (old version - see also ndbm(3X)) dbm(3X) 

data created by record widget, save sound bucket AuSaveFile(3X) 

data format, convert audio file AConvertAFile(3X) 

data from a file, read read(2) 

data from NetlPC option buffer, obtain option code and readopt(3N) 

data, get character or word from a stream file getc(3S) 

data, get wide character from a stream file getwc(3C) 

datalock ( ) - lock process into memory after allocating data and stack space datalock(3C) 

data order, convert string strord(3C) 

data path width (in bits), set Jo_width_ctl(3I) 

data pointer for binary search tree, get tsearch(3C) 

data representation, library routines for external xdr(3C) 

data segment and shared memory, attach or detach shmop(2) 

data segment space allocation, change .brk(2) 

data, send on a virtual circuit connection ipcsend(2) 

data, text, or process, lock in memory .plock(2) 

data to a file, write .write(2) 

data to check the network, scatter .spray(3N) 

data to NetlPC option buffer, add argument and addopt(3N) 

data transfer rate, inform system of required minimum I/O io_speed_ctl(3l) 

date and time, convert to string .ctime(3C) 

date and time, convert to string strftime(3C) 

date and time, convert to wide-character string wcsftime(3C) 

date and time, convert user format .getdate(3C) 

date and time, get more precisely (Version 7 compatibility only) ftime(2) 

date and time, get or set system clock gettimeofday(2) 

date and time, set stime(2) 

daylight ( ) - Daylight Savings Time flag ctime(3C) 

dbm_clearerr ( ) - reset error condition on named database ndbm(3X) 

dbm_close ( ) - close an open database ndbm(3X) 

dbmclose ( ) - close currently open database (old single-data-base version) dbm(3X) 

dbm_delete ( ) - delete a database key and associated contents ndbm(3X) 

dbm_error ( ) - error in reading or writing in a database ndbm(3X) 

dbm_fetcli() - access a database entry under a key ndbm(3X) 

dbm_firstkey() - get first key in a database ndbm(3X) 

dbminit ( ) - open a single database (old single-data-base version) dbm(3X) 

dbm_nextkey ( ) - get next key in a database , ndbm(3X) 

dbm_open( ) - open a database for access ndbm(3X) 

dbm_store ( ) - store an entry under a key in a database ndbm(3X) 

decimal ASCII string, convert long integer to ltostr(3C) 

decimal library, packed, HP 3000-mode Jbppac(3X) 

define additional signal stack space sigspace(2) 

define interface parallel poll response hpib_ppoll_resp_ctl(3l) 

define I/O device interrupt (fault) conditions io_on_interrupt(3l) 

define what to do upon receipt of a signal signal(2) 

degree-valued trigonometric functions ..trigd(3M) 

delete, add, or modify delete access control list entry setaclentry(3C) 

delete allocated signal stack space sigspace(2) 

delete a node from a binary search tree tsearch(3C) 

delete ( ) - delete key and data under it (old single-data-base version) dbm(3X) 
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delete file or directory name; remove directory entry unlink(2 

delete name associated with a call socket or destination call socket ipcnamerase(2 

dequeue and return first event in audio event queue ANextEvent(3X 

descend a directory hierarchy recursively itw(3C 

description of disk by its name, get getdiskbynasne(3C) 

descriptor, close a file close(2 

descriptor, create a destination ipcdest(2 

descriptor file entry, get file system (BSD 4.2 compatibility only) getfsent(3X 

descriptor, map stream pointer to file £leno(3S 

descriptor, obtain a destination ipclookup(2 

descriptor, release a .......................... ipcshutdown(2) 

destination call socket, associate name with call socket or ipcname(2 

destination call socket, delete name associated with a call socket or ipcnamerase(2 

destination descriptor, create a ipcdest(2 

destination descriptor, obtain a ipclookup(2 

destroy specified sound bucket ADestroySBucket(3X 

detach shared memory from data segment shmop(2 

determine accessibihty of a file Access(2 

determine current signal stack space sigspace(2 

determine how last I/O read terminated io_get_term_reason(3l 

determine status of call socket or VC socket ipcselect(2 

device file, FIFO, make a jnkfifo(3C 

device for interleaved paging/swapping, add a swap swapon(2 

device ID to file path, map devnm(3 

device I/O interrupt (fault) control io_on_interrupt(3l' 

device special file, control character Joctl(2 

devnm( ) - map device ID to file path devnm(3 

dial ( ) , undial ( ) - establish an out-bound terminal line connection dial(3C 

dif f time ( ) - difference between two calendar time values ctime(3C 

directory: access, open, or close a directory and associated directory stream directory(3C 

directory: change root directory .chroot(2 

directory: change working directory .chdir(2 

directory: delete file or directory name; remove directory entry unlink(2 

directory: get entries in a filesystem-independent format getdirentries(2 

directory: get path-name of current working directory getcwd(3C 

directory: make a directory file jnkdir(2 

directory: make a directory, or a special or ordinary file mknod(2 

directory: remove a directory file xmdir(2 

directory: scan a directory scandir(3C 

directory entry, remove; delete file or directory name unlink(2 

directory file, remove a rmdir(2 

directory hierarchy, recursively descend a ftw(3C 

directory pointer array, sort a .scandir(3C 

directory, scan a scandir(3C 

directory stream, directory and associated, open for access directory(3C' 

disable/enable odd parity on ATN commands hpib_parity_ctl(3l) 

disable or enable I/O interrupts for the associated eid( ) io_interrupt_ctl(3l 

disable or enable process accounting .acct(2 

disk description by its name, get getdiskbyname(3C 

disk, flush buffers to sync(2 

diskless cluster nodes, get a list of active cnodes(2 

diskless cnode ID of local machine, get cnodeid(2 

disk quotas, manipulate .quotactl(2 

disk storage, preallocate fast .prealloc(2 

disk, synchronize a file's in-core state with its state on fsync(2 

distance function, Eucfidean (hypotenuse) .hypot(3M) 

division and remainder, integer div(3C 

div(), ldiv() -integer division and remainder div(3C 
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DMA allocation for an interface, control io_dma_ctl(3l) 

dn_comp ( ) - resolver routines .resolver(3N) 

dn_expand( ) - resolver routines jcesolver(3N) 

domain, get or set name of current NIS getdomainname(2) 

double-precision number, convert string to strtod(3C) 

double-precision number, convert string to long strtold(3C) 

double-precision number, convert wide character string to wcstod(3C) 

drand48 ( ) , erand48 ( ) - generate double-precision pseudo-random numbers drand48(3C) 

drem( ) - remainder manipulations ieee(3M) 

dup2 ( ) - duplicate an open file descriptor to a specific slot dup2(2) 

dup ( ) - duplicate an open file descriptor dup(2) 

duplicate an open file descriptor dup (2) 

duplicate an open file descriptor to a specific slot dup2(2) 

duplicate entries in a table, eliminate lsearch(3C) 

dynamic file system swapping .swapon(2) 

echo, suppress while reading password from terminal getpass(3C) 

ecvt ( ) , f cvt ( ) - convert floating-point number to string ecvt(3C) 

edata - first address beyond initialized program data region end(3C) 

effective access rights to a file, get a user's getaccess(2) 

effective or real user or group ID, get getuid(2) 

effective, real, and/or saved user or group IDs, set setresuid(2) 

element, convert floating-point number to string or string array ecvt(3C) 

ehminate duplicate entries in a table Jsearch(3C) 

emulate /etc/termcap access routines termcap(3X) 

enable asynchronous faults pfm_$enable(3) 

enable asynchronous faults pfm_$enable_faults(3) 

enable/disable odd parity on ATN commands hpib_parity_ctl(3l) 

enable or disable I/O interrupts for the associated eid( ) io_interrupt_ctl(3l) 

enable or disable process accounting .acct(2) 

enable SRQ line on HP-IB, allow interface to hpib_rqst_srvce(3l) 

encrypt () - generate hashing encryption crypt(3C) 

encryption, hashing, generate : crypt(3C) 

encryption, password x;rypt(3C) 

endccent ( ) - close cluster configuration file getccent(3C) 

endexportent ( ) - access exported file system information ...exportent(3N) 

end - first address beyond uninitialized program data region end(3C) 

endf sent ( ) - close file system descriptor file getfsent(3X) 

endgrent ( ) - close currently open group ( ) file getgrent(3C) 

endhostent ( ) - get network host entry gethostent(3N) 

end locations of allocated regions in program end(3C) 

endmntent ( ) - close file system description file getmntent(3X) 

endnetent ( ) : get network entry getnetent(3N) 

endnetgrent () - get network group entry getnetgrent(3C) 

endpoint for communication, create an .socket(2) 

endprotoent ( ) - get protocol entry getprotoent(3N) 

endpwent ( ) - close currently open password file getpwent(3C) 

endservent ( ) : get service entry getservent(3N) 

endspwent ( ) - close currently open secure password file ....getspwent(3C) 

endusershell ( ) - close legal user shells file getusershell(3C) 

endutent ( ) - close currently open utmp ( ) file getut(3C) 

entries from a directory, get in a filesystem-independent format getdirentries(2) 

entries from name list, get nlist(3C) 

entries in a table, ehminate duplicate lsearch(3C) 

entry from cluster configuration file, get getccent(3C) 

entry from group ( ) file, get getgrent(3C) 

entry from password file, get .getpwent(3C) 

entry from secure password file, get getspwent(3C) 

entry, get file system description file getmntent(3X) 
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entry, get file system descriptor file (BSD 4.2 compatibility only) getfsent(3X) 

entry, get or set protocol .getprotoent(3N) 

entry, get RPC getrpcent(3C) 

entry, network group, get or set getnetgrent(3C) 

entry, service, get or set ....„„.,,.......... getservesit(3N) 

entry, write password file .putpwent(3C) 

environment, change or add value to .putenv(3C) 

environment, clear the process clearenv(3C) 

environment list, search for value of specified variable name getenv(3C) 

environment of a program, initialize the NLS nl_init(3C) 

environment, save/restore stack for non-local goto setjmp(3C) 

environment variable, search environment list for value of getenv(3C) 

EOI mode for HP-IB file, control .Jhpib_eoi_ctl(3l) 

erf ( ) , erf c ( ) - error function and complementary error function erf(3M) 

errno ( ) - error indicator for system calls errno(2) 

ertno - system error messages .perror(3C) 

error_$c_get_text ( ) - return subsystem, module, and error texts for a status code error_$c_get_text(3) 

error_$c_text ( ) - return an error message for a status code error_$c_text(3) 

error function and complementary error function erf(3M) 

error-handling function, math library matherr(3M) 

error indicator for system calls «rrno(2) 

error_$intro- error text database operations error_$intro(3) 

error message for a status code, return an error_$c_text(3) 

error messages, system perror(3C) 

error number, provide text describing NetlPC ipcerrmsg(3N) 

error text database operations error_$intro(3) 

error texts for a status code, return subsystem, module, and error_$c_get_text(3) 

establish a cleanup handler pfm_$cleanup(3) 

establish an out-bound terminal line connection dial(3C) 

establish NetlPC virtual circuit connection ipcrecv(2) 

establish time limit for I/O operations io_timeout_ctl(3l) 

/etc/termcap access routines, emulate .termcap(3X) 

etext - first address beyond program text region end(3C) 

Euclidean distance (hypotenuse) function hypot(3M) 

event handler for this connection, add audio Atlnitialize(SX) 

events and system calls currently being audited, get , getevent(2) 

events and system calls to be audited setevent(2) 

examine and change blocked signals sigprocmask(2) 

examine and change signal action sigaction(2) 

examine pending signals sigpending(2) 

exception flags (floating-point), examine and set fpgetround(3M) 

exceptions, managing signal .pfm_$intro(3) 

exception trap enable bits (floating-point), examine and set fpgetround(3M) 

execl(), execleO, execlpO, execvO, execve(), execvpO - execute an object-code file exec(2) 

execute an object-code file «xec(2) 

execute a regular expression against a string regcmp(3X) 

execution profile, prepare jnonitor(3C) 

execution startup routines, C, Pascal, and Fortran crt0(3) 

execution, suspend for interval sleep(3C) 

execution time profile profil(2) 

existing file, truncate to zero for rewriting creat(2) 

exit a program pgm_$exit 

exit ( ) , _exit ( ) - terminate process .exit(2) 

exiting cleanup handlers .pfm_$signal(3) 

exit, register a function to be called at .atexit(2) 

expansions, perform word .wordexp(3C) 

exp ( ) , expf ( ) - exponential functions .exp(3M) 

expf (), exp() - exponential functions .exp(3M) 
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explicit load of shared libraries jshlJoad(SX) 

exponent and mantissa, split floating-point into frexp(SC) 

exponential, logarithm, power, square root, cube root functions exp(3M) 

exponent manipulations ieee(3M) 

exported file system information, access exportent(SN) 

export ent ( ) - access exported file system information exportent(3N) 

expression matching routines, regular jregcomp(3C) 

expression, regular, compile and match routines regexp(3X) 

expression, regular, compile or execute against a string regcmp(3X) 

external data representation, library routines for xdr(3C) 

fabs(), fabsf (), floor (), a«il(), fmod(), 

fmodf ( ) , rlnt ( ) - absolute value, floor, ceiling, remainder, round-to-nearest functions floor(3M) 

fabsf ( ) , f abs ( ) , floor ( ) , ceil ( ) , f mod ( ) , 

fmodf ( ) , rlnt ( ) - absolute value, floor, ceiling, remainder, round-to-nearest functions floor(3M) 

facilities, software signal sigvector(2) 

fast disk storage, preallocate .prealloc(2) 

fault, generate anIOT abort(3C) 

fault (interrupt) conditions, define for I/O device io_on_interrupt(3l) 

fault management pfm_$intro 

faults, enable asynchronous pfm_$enable(3) 

faults, enable asynchronous .pfm_$enable_faults(3) 

faults, inhibit asynchronou s but allow time-sliced task switching pfm_$inhibit_faults(3) 

faults, inhibit asynchronous pfm_$inbibit(3) 

f chdir ( ) - change working directory .chdir(2) 

fchmodO -change access mode (permissions) of file chmod(2) 

f chovm( ) - change owner and group of a file chown(2) 

f close ( ) - flush buffer then close stream fclose(3S) 

f cntl ( ) - open-file control fcntl(2) 

f cpacl ( ) - copy access control list (ACL) to another file cpacl(3C) 

f cvt ( ) , ecvt ( ) - convert floating-point number to string ecvt(3C) 

f dopen( ) - associate a stream with an open file descriptor fopen(3S) 

f eof ( ) - check for end-of-file error on stream ferror(3S) 

f error ( ) - check for I/O error on stream ferror(3S) 

fetch ( ) - access data under a key (old single-data-base version) dbm(3X) 

fflushO - flush buffer without closing stream fclose(3S) 

f f s ( ) - BSD find first set bit jmemory(3C) 

f getacl ( ) - get access control fist (ACL) information getad(2) 

f getccent ( ) - get pointer to cluster configuration entry in a stream getccent(3C) 

f getc ( ) , getc ( ) - get character from a stream file getc(3S) 

f getgrent ( ) - get next entry in group ( ) -file-formatted input stream getgrent(3C) 

f getpos ( ) - save file position indicator for a stream fgetpos(3S) 

f getpwent ( ) - get next entry in password-file-formatted input stream getpwent(3C) 

f gets ( ) , gets ( ) - get a string from a standard input stream gets(3S) 

f getspwent ( ) - get next entry in secure password-file-formatted input stream getspwent(3C) 

f getwc ( ) , getwc ( ) - get wide character from a stream file getwc(3C) 

f getws ( ) , getws ( ) - get a wide string from a standard input stream getws(3C) 

FIFO special file, make a mkfifo(3C) 

file: access wtmp ( ) or utmp ( ) file .getut(3C) 

file: assign buffering to a stream file .setbuf(3S) 

file: change access mode (permissions) of file chmod(2) 

file: change owner and group of a file .chown(2) 

file: change the name of a file rename(2) 

file: close a file descriptor jclose(2) 

file: copy access control fist (ACL) to another file cpacl(3C) 

file: create a name for a temporary file tmpnam(3S) 

file: create a new file or rewrite an existing one creat(2) 

file: create a temporary file .tmpfile(3S) 

file: delete file or directory name; remove directory entry unlink(2) 
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file: determine accessibility of a file access(2) 

file: execute an object-code file .exec (2) 

file: get file status stat(2) 

file: link additional name to an existing file link(2) 

file: make a director^ file or a special or ordinar v file mknod/2^ 

file: make a symbolic link to a file symlink(2) 

file: make a unique (usually temporary) file name mktemp(3C) 

file: open a file for reading or writing .open (2) 

file: open-file control routines fcntl(2) 

file: print formatted output with numbered arguments to a file or string printmsg(3C) 

file: read data from a file , , ,,,„read(2) 

file: read from file, stream, or character string with formatted input conversion scanf(3S) 

file: remove a directory file rmdir(2) 

file: remove a file remove(3C) 

file: rewrite an existing file .creat(2) 

file: truncate a file to a specified length truncate(2) 

file: truncate an existing file to zero for rewriting creat(2) 

file: write data to a file .write(2) 

file access and modification times, set or update utime(2) 

file attributes of specified file, get AGetAFileAttributes(3X) 

file, CDF: return process context for context-dependent file search, return getcontext(2) 

file, cluster configuration: get entry from cluster configuration file getccent(3C) 

file creation (permissions) mask, set and get umask(2) 

file data format, convert audio AConvertAFile(3X) 

file descriptor: duplicate an open file descriptor dup(2) 

file descriptor: duplicate an open file descriptor to a specific slot dup2(2) 

file descriptor, map stream pointer to £leno(3S) 

file entry, get file system description getmntent(3X) 

file entry, get file system descriptor (BSD 4.2 compatibility only) getfsent(3X) 

file, get a user's effective access rights to a getaccess(2) 

file, get file attributes of specified AGetAFileAttributes(3X) 

file, group: get entry from group ( ) file getgrent(3C) 

file handle for file on remote node, get getfh(2) 

file locking: provide semaphores and record locking on files lockf(2) 

filename generation function glob(3C) 

filename of controlling terminal, generate ctermid(3S) 

filename patterns, match fnmatch(3C) 

filenoO - get integer file descriptor for stream ferror(3S) 

f ileno ( ) - map stream pointer to file descriptor fileno(3S) 

file on remote node, get file handle for getfh(2) 

file or anonymous memory region, initialize semaphore in mapped msem_init(2) 

file or anonymous region, remove semaphore in mapped msem_remove(2) 

file, password: get entry from password file getpwent(3C) 

file, password: get entry from secure password file getspwent(3C) 

file path, map device ID to .devnm(3) 

file path names, manipulate context-dependent getcdf(3C) 

file pointer: move read/write file pointer Jseek(2) 

file position indicator for a stream, save or restore fgetpos(3S) 

files, audit, set or get audctl(2) 

file search: return process context for context-dependent file search getcontext(2) 

file's in-core state with its state on disk, synchronize a fsync(2) 

file size limits and break value, get or set ulimit(2) 

file, stream: buffered binary input/output to a stream file fread(3S) 

file, stream: convert file to stream; open or re-open a stream file fopen(3S) 

file, stream: get character or data word from a stream file getc(3S) 

file, stream: get wide character from a stream file getwc(3C) 

file, stream: open or re-open a stream file; convert file to stream fopen(3S) 

file, stream: reposition or get pointer for I/O operations on a stream file fseek(3S) 
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file, synchronize a mapped jnsync(2) 

file system: get file system description file entry getmntent(3X) 

file system: get file system descriptor file entry (BSD 4.2 compatibility only) getfsent(3X) 

file system: get file system statistics statfs(2) 

file system: get mounted file system statistics ustat(2) 

file system: mount a file system .vfsmount(2) 

file system: mount a removable file system mount(2) 

file system: unmount a file system umount(2) 

file system control fsctl(2) 

file system information, access exported exportent(3N) 

file systems, keep track of remotely mounted mount(3N) 

file system statistics, get statfsdev(3C) 

file system swapping swapon(2) 

file tree: walk a file tree ftw(3C) 

file, utmp ( ) , of the current user, find the slot in the ttyslot(3C) 

find name of a terminal .ttyname(3C) 

find out if audio controller restricts gain entries AGMGainRestricted(3X) 

find the slot in the utmp ( ) file of the current user ttyslot(3C) 

finish stream data conversion AEndConversion(3X) 

f initef ( ) , finite ( ) - floating-point classification functions ieee(3M) 

finite ( ) , f initef ( ) - floating-point classification functions ieee(3M) 

f irstkey ( ) - get first key in database (old single-data-base version) dbm(3X) 

first locations beyond allocated program regions end(3C) 

f irstof 2 ( ) , PiRSTof 2 ( ) - test for valid first byte in 16-bit character nl_tools_16(3C) 

flag for calling process, get audit process getaudproc(2) 

floating-point: convert floating-point number to string or string array element ecvt(3C) 

floating-point: convert string to floating-point number cvtnum(3C) 

floating-point: split floating-point into mantissa and exponent frexp(3C) 

floating-point classification functions ipclassify(3M) 

floating-point classification functions ieee(3M) 

floating-point classification functions isinf(3M) 

floating-point classification functions isnan(3M) 

floating-point mode control functions fpgetround(3M) 

floating-point number to string, convert long double ldcvt(3C) 

floor ( ) , ceil ( ) , fmod( ) , fmodf ( ) , f abs ( ) , f absf ( ) , 

rint ( ) - floor, ceiling, remainder, absolute value, round-to-nearest functions floor(3M) 

floor, ceiling, remainder, absolute value, round-to-nearest functions floor(3M) 

flush and/or purge the cache cachectl(3C) 

flush buffers to disk sync(2) 

flush buffer with or without closing stream fclose(3S) 

f modf (), f mod (), ceil (), floor (), f abs () , 

f absf ( ) , rint ( ) - remainder, ceiling, floor, absolute value, round-to-nearest functions floor(3M) 

fmod( ) , fmodf ( ) , ceil( ) , f loor ( ) , f abs ( ) , 

f absf ( ) , rint ( ) - remainder, ceiling, floor, absolute value, round-to-nearest functions floor(3M) 

f nmatch ( ) - match filename patterns fnmatch(3C) 

fopen() -open a named file and associate with a stream fopen(3S) 

foreground process group ID, get tcgetpgrp(3C) 

foreground process group ID, set .tcsetpgrp(3C) 

fork ( ) - create a new process fork(2) 

format, convert audio file data AConvertAFile(3X) 

format date and time, convert user getdate(3C) 

formatted input conversion, read from stream file or character string scanf(3S) 

formatted input conversion to a varargs argument vscanf(3S) 

formatted output of a varargs argument list, print vprintf(3S) 

formatted output, print to standard output, file, or string printf(3S) 

formatted output with numbered arguments, print to a file or string printmsg(3C) 

formatted read and conversion from stream file or character string scanf(3S) 

formatting conventions, numeric, of current locale, query localeconv(3C) 
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Fortran execution startup routines xjrt0(3) 

fpathconf ( ) - get configurable pathname variables pathconf(2) 

fpclassifyf ( ) , fpclassify ( ) - floating-point classification functions fpclassify(3M) 

fpclassify ( ) , fpclaasifyf ( ) - floating-point classification functions fpclassify(3M) 
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fpgetf astmode ( ) , fpsetf astmode ( ) - examine and set floating-point underflow mode fpgetround(3M) 

fpgetmask ( ) , f psetmask ( ) - examine and set floating-point exception trap enables fpgetround(3M) 

fpgetroundO, fpsetroundO -examine and set floating-point rounding mode .. fpgetround(3M) 

fpgetstickyO, fpsetstickyO -examine and set floating-point exception flags fpgetround(3M) 

fprintf ( ) , nl_fprintf ( ) - print formatted output to a file printf(3S) 

£ *^27intmsc ( \ — ^rint formatted output with numbered arguments to a file -r| innt-ms**'3C' 

fpsetcontrol ( ) , fpgetcontrol ( ) - examine and set floating-point control register fpgetround(3M) 

fpsetdef aults ( ) - set floating-point control register defaults fpgetround(3M) 

fpsetf astmode ( ) , f pgetf astmode ( ) - examine and set floating-point underflow mode fpgetround(3M) 

f psetmask ( ) , fpgetmask ( ) - examine and set floating-point exception trap enables fpgetround(3M) 

fpsetroundO, fpgetroundO -examine and set floating-point rounding mode fpgetround(3M) 

f psetsticky ( ) , f pgetsticky ( ) - examine and set floating-point exception flags fpgetround(3M) 

fputc ( ) , putc ( ) - put character on a stream putc(3S) 

fputs ( ) - write null-terminated string to a named stream file puts(3S) 

fputwc ( ) , putwc ( ) - put wide character on a stream putwc(3C) 

fputws ( ) - write null-terminated wide string to a named stream file fputws(3C) 

fread(), f write O - buffered binary input/output to a stream file fread(3S) 

free a per-process timer .rmtimer(3C) 

free ( ) - release allocated block of main memory malloc(3C) 

f reopen ( ) - substitute a named file in place of an already open stream fopen(3S) 

f rexp ( ) , ldexp ( ) , modf ( ) - split floating-point into mantissa and exponent frexp(3C) 

frtO.o, mfrtO.o- FORTRAN execution startup routines crt0(3) 

f scanf ( ) , nl_f scanf ( ) - formatted read from named input stream file scanf(3S) 

f sctl ( ) - file system control fsctl(2) 

f seek ( ) , rewind ( ) , f tell ( ) - reposition a file pointer in a stream fseek(3S) 

f seek () - set position of next I/O operation on stream file fseek(3S) 

f setaclentry ( ) - add, modify, or delete access control list entry setaclentry(3C) 

fsetaclO - set access control list (ACL) information setacl(2) 

f setpos () - restore file position indicator for a stream fgetpos(3S) 

f statfsdevO, statfsdevO -get file system statistics statfsdev(3C) 

f statf s ( ) , statf s ( ) - get file system statistics statfs(2) 

f stat ( ) , (stat ( ) , lstat ( ) ) - get open file status stat(2) 

f sync ( ) - synchronize a file's in-core state with its state on disk fsync(2) 

f tell ( ) - get offset from beginning-of-file of current byte in stream file fseek(3S) 

f time ( ) - get date and time more precisely (Version 7 compatibility only) ftime(2) 

f tok ( ) - standard interprocess communication package stdipc(3C) 

ftruncateO, truncate () -truncate a file to a specified length truncate(2) 

ftw(),ftwh() nftwO - walk a file tree ftw(3C) 

function: Bessel functions .bessel(3M) 

function: complex absolute value Jiypot(3M) 

function: Euclidean distance (hypotenuse) hypot(3M) 

function: hyperbolic trigonometric functions sinh(3M) 

function: inverse hyperbolic trigonometric functions asinh(3M) 

function: log gamma gamma(3M) 

function: trigonometric functions (degrees) trigd(3M) 

function: trigonometric functions , .trig(3M) 

function to be called at program termination, register a atexit(2) 

fwriteO, freadO - buffered binary input/output to a stream file fread(3S) 

gain, get system or monitor audio channel AGetSystemChannelGain(3X) 

gain, get transaction channel AGetChannelGain(3X) 

gain, set system or monitor audio channel ASetSystemChannelGain(3X) 

gain, set transaction channel ASetChannelGain(3X) 

gamma function, log gamma(3M) 

848 Index: Volume 2 



Index 

Volume 2 

Description Entry Name(Section 

gamma(), IgammaO, signgamO - log gamma function gamma(3M 

gcrtO.o, gfrtO.o- C and Pascal execution startup routines crt0(3 

gcvt (), nl_gcvt ( ) -convert floating-point number to string array element ecvt(3C 

generate an IOT fault abort(3C 

generate file name of controlling terminal ctermid(3S 

generate file names glob(3C 

generate hashing encryption .crypt(3C 

generate uniformly distributed pseudo-random numbers drand48(3C 

generator, simple random-number jcand(3C 

get: character or data word from a stream file getc(3S 

get: data pointer for binary search tree tsearch(3C 

get: date and time more precisely (Version 7 compatibility only) ftime(2 

get: diskless cnode ID of local machine cnodeid(2 

get: entries from a directory in a filesystem-independent format getdirentries(2 

get: entries from name list jilist(3C 

get: entry from group ( ) file .getgrent(3C 

get: file size limits and break value, get or set ulimit(2 

get: file status stat(2 

get: file system description file entry getmntent(3X 

get: file system descriptor file entry (BSD 4.2 compatibility only) getfsent(3X' 

get: file system statistics statfs(2 

get: list of active nodes in diskless cluster cnodes(2 

get: message from an NLS message catalogue catgetmsg(3C 

get: message queue jnsgget(2 

get: mounted file system statistics .ustat(2 

get: name and version of current HP-UX system uname(2 

get: name of current host gethostname(2 

get: NLS program message .cat gets (3 C 

get: option letter from argument vector getopt(3C 

get: path-name of current working directory getcwd(3C 

get: pointer for I/O operations on a stream file, get or reposition fseek(3S 

get: pointer to login name inutmpO getlogin(3C 

get: process and child process times .times (2 

get: process context for context-dependent file search getcontext(2 

get: process priority getpriority(2 

get: process, process group, or parent process ID getpid(2 

get: real or effective user or group ID getuid(2 

get: set of semaphores semget(2 

get: shared memory segment shmget(2 

get: system clock date and time gettimeofday(2 

get: time time (2 

get: value of process interval timer getitimer(2 

get: wide character from a stream file getwc(3C 

get access control list (ACL) information getacl (2 

getaccess ( ) - get a user's effective access rights to a file getaccess(2 

getacl ( ) , f getacl ( ) - get access control list (ACL) information getacl(2 

get address of connected peer getpeername(2 

get and/or set signal stack context .sigstack(2 

get a silence value AGetSilenceValue(3X 

getaudid() -get audit ID (aid ()) for current process getaudid(2 

get audit ID (aid ( ) ) for current process getaudid(2 

get audit process flag for calling process getaudproc(2 

getaudproc ( ) - get audit process flag for calling process getaudproc(2 

get a user's effective access rights to a file getaccess(2 

get best audio attribute setting for specified controller ABestAudioAttributes(3X 

get bit order used for one-bit-per-sample data ASoundBitOrder(3X 

get byte order of audio data accepted by audio controller for this connection ASoundByteQrder(3X 

getcccid( ) - get cluster configuration file entry matching specified id( ) getccent(3C 
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getccent ( ) - get entry in cluster configuration file getccent(3C) 

getccnamf ) -get cluster configuration file entry matching specified name ( ) getccent(3C) 

getcdf ( ) — manipulate context-dependent file path names getcdf(3C) 

getc ( ) , f getc ( ) - get character from a stream file getc(3S) 
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getclock — get current value of system- wide clock getclock(3C) 

get configurable pathname variables pathconf(2) 

get configurable system variables .sysconf(2) 

get connection number for specified audio server connection AConnectionNumber(3X) 

get context ( ) - return the process context for context-dependent file search getcontext(2) 

cet current value of s v stem-wide clock getclock(3C) 

getcwdO —get path-name of current working directory getcwd(3C) 

get D/A output channels existing on current hardware AOutputChannels(3X) 

get data formats for a specifed file format AGetDataFormats(3X) 

getdateO - convert user format date and time getdate(3C) 

getdirentries ( ) - get entries from a directory in a filesystem-independent format getdirentries(2) 

getdiskbyname ( ) - get disk description by its name getdiskbyname(3C) 

get disk description by its name getdiskbyname(3C) 

getdomainname ( ) -get name of current NIS domain getdomainname(2) 

getegid() -get effective group ID .getuid(2) 

getenvO —return value for environment name „ getenv(3C) 

geteuidO -get effective user ID .getuid(2) 

getevent ( ) - get events and system calls currently being audited getevent(2) 

get events and system calls currently being audited getevent(2) 

ge t export ent ( ) - access exported file system information exportent(3N) 

getexportopt ( ) - access exported file system information exportent(3N) 

getfhO -file handle for file on remote node getfh(2) 

get file attributes of specified file AGetAPileAttributes(3X) 

get file format of specified file AQueryAFile(3X) 

get file handle for file on remote node getfh(2) 

get file system statistics statfsdev(3C) 

get first event found in audio event queue ACheckEvent(3X) 

get first event in audio event queue that matches mask ACheckMaskEvent(3X) 

get first matching event in audio event queue AMaskEvent(3X) 

get foreground process group ID tcgetpgrp(3C) 

get f sent ( ) - get next fine in file system descriptor file getfsent(3X) 

getfsfileO - search descriptor file for ordinary file entry getfsent(3X) 

getf sspec ( ) - search descriptor file for special (device) file entry getfsent(3X) 

getfstypeO - search descriptor file for specified file type entry getfsent(3X) 

getgidO —get real group ID getuid(2) 

getgrent ( ) - get next entry in group ( ) file getgrent(3C) 

getgrgidO -get entry from group ( ) file that matches gid() getgrent(3C) 

getgrnam( ) -get entry from group ( ) file that matches group name name() getgrent(3C) 

getgroups ( ) - get group access list getgroups(2) 

gethcwd ( ) - get path-name of current working directory including diskless hidden directories getcwd(3C) 

gethostbyaddr ( ) - get network host entry gethostent(3N) 

gethostbyname ( ) - get network host entry gethostent(3N) 

gethostent ( ) - get network host entry gethostent(3N) 

get host name ( ) - get name of current host gethostname(2) 

get information about shared library shl_load(3X) 

getitimer () - get value of process interval timer getitimer(2) 

get legal user shells getusershell(3C) 

get fist of A/D input channels on current hardware AInputChannels(3X) 

get fist of data formats supported by audio controller ADataFormats(3X) 

getlocale ( ) - get the locale of a program setlocale(3C) 

getlogin( ) - get pointer to login name in utmp ( ) getlogin(3C) 

get major version number of protocol used by audio server AProtocolVersion(3X) 

get maximum input gain supported by audio controller AMaxInputGain(3X) 
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get maximum output gain supported by audio controller AMaxOutputGain(3X) 

get minimum input gain supported by audio controller AMinInputGain(3X) 

get minimum output gain supported by audio controller AMinOutputGain(3X) 

get minor revision number of protocol used by audio server AProtocolRevision(3X) 

getmntent ( ) - get a file system description file entry getmntent (3X) 

get_myaddress ( ) - get machine's IP address jrpc(3C) 

get name of audio controller (string) passed to AOpenAudio() AAudioString(3X) 

get name of current NIS domain rt etdom&innBme(2) 

getnetbyaddr ( ) : get network entry getnetent(3N) 

getnetbyname ( ) : get network entry getnetent(3N) 

getnetent ( ) : get network entry getnetent(3N) 

getnetgrent ( ) - get network group entry getnetgrent(3C) 

get network entry getnetent(3N) 

get network group entry .getnetgrent (3 C) 

get network host entry .gethostent(3N) 

get number of events in queue for specified server connection AEventsQueued(3X) 

getopt ( ) , optarg, optind, opterr - get option letter from argument vector getopt(3C) 

get or set audit files audctl(2) 

get or set tty baud rate .cfspeed(3C) 

getpass ( ) - read a password from terminal while suppressing echo getpass(3C) 

getpeername ( ) - get address of connected peer getpeername(2) 

getpgrp2 () - get process group ID of specified process getpid(2) 

getpgrp ( ) - get process group ID getpid(2) 

getpid( ) - get process ID .getpid(2) 

get play volume or record gain of specified transaction AGetGain(3X) 

getppidO -get parent process ID getpid(2) 

getpriority - get process priority getpriority(2) 

getprotobyname ( ) - get protocol entry getprotoent(3N) 

getprotobynumber ( ) -get protocol entry getprotoent(3N) 

get protocol entry .getprotoent(3N) 

getprotoent ( ) - get protocol entry getprotoent(3N) 

getpwent ( ) - get next password file entry getpwent(3C) 

getpw() -get name from UID (obsolete) getpw(3C) 

getpwnam( ) - get password file entry matching login name name ( ) getpwent(3C) 

getpwuidO -get password file entry matching uid ( ) getpwent(3C) 

getrlimit ( ) - set system resource consumption limit getrlimit(2) 

getrpcbyname ( ) : get RPC entry getrpcent(3C) 

getrpcbynumber ( ) : get RPC entry getrpcent(3C) 

getrpcent ( ) : get RPC entry .getrpcent(3C) 

get RPC entry .getrpcent (3C) 

getrpcport ( ) - get RPC port number getrpcport(3N) 

get RPC port number .getrpcport (3N) 

getservbyname ( ) : get service entry getservent(3N) 

getservbyport ( ) : get service entry getservent(3N) 

getservent ( ) : get service entry getservent(3N) 

get service entry getservent (3N) 

gets ( ) , f gets ( ) - get a string from a standard input stream gets(3S) 

get socket address .getsockname(2) 

getsockname ( ) - get socket address getsockname(2) 

getsockopt ( ) - get options on sockets getsockopt(2) 

getspwaid() -get next secure password file audit ID getspwent(3C) 

getspwent ( ) - get next secure password file entry getspwent(3C) 

getspwnam( ) - get secure password file entry matching login name name ( ) getspwent(3C) 

getspwuidO -get secure password file entry matching uid ( ) getspwent(3C) 

get status of specified transaction .AGetTransStatus(3X) 

getsubopt ( ) - parse suboptions from a string getsubopt(3C) 

get system or monitor audio channel gain AGetSystemChannelGain(3X) 

get system resource consumption limit getrlimit (2) 
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get the locale of a program jsetlocale(3C 

get the name of a slave pty .ptsname(3C 

gettimeofdayO - get system clock date and time gettimeofday(2 

gettimer- get value of a per-process timer gettimer(3C 

get transaction channel gain AGeiCnannelGain(3X) 

gettransient ( ) - get a program number in the transient range rpc(3C 

get tty device operating parameters tcattribute(3C 

get types of input sources existing on current hardware AInputSources(3X 

get types of output destinations existing on current hardware AOutputDestinations(3X' 

getuidO -get real user ID getuid(2 



getutent ( ) - get pointer to next entry in a utmp ( ) file getut(3C 

getutidO - get pointer to entry matching id ( ) inautmpO file getut(3C 

getutline() - get pointer to entry matching line ( ) inautmpO file getut(3C 

get value of a per-process timer .gettimer(3C 

get vendor name of audio server for this connection AServerVendor(3X 

get vendor release number of audio server for this connection AVendorRelease(3Xi 

getwc(), fgetwcO -get wide character from a stream file getwc(3C 

getwchar( ) - get wide character from standard input fAe getwc(3C 

getw() - get data word (integer) from a stream file getc(3S 

getws ( ) , f getws ( ) - get a wide string from a standard input stream getws(3C 

gfrtO.o, gcrtO.o- C and Pascal execution startup routines crt0(3 

glob() : -file name generation function glob(3C 

globf ree ( ) : - file name generation function glob(3C 

gmtime() -convert date and time to Greenwich Mean Time ctime(3C 

goto, save/restore stack environment for non-local setjmp(3C 

GPIO: return status fines of GPIO card gpio_get_status(3F 

GPIO: set control fines on GPIO card gpio_set_ctl(3^ 

gpio_get_status ( ) - return status fines of GPIO card gpio_get_status(3Ii 

gpio_set_ctl ( ) - set control lines on GPIO card gpio_set_ctl(3F 

group access fist: get group access list getgroups(2 

group access list: initialize group access list initgroups(3C 

group access list: set group access list setgroups(2 

group and/or owner, change in access control hst (ACL) chownacl(3C 

group and owner of a file, change .chown(2 

group entry, network, get or set getnetgrent(3C 

group ( ) file, get entry from getgrent(3C 

group ID: get real or effective group ID getuid(2 

group ID: set group ID setuid(2 

group ID: set real, effective, and/or saved group or user IDs setresuid(2 

group ID, create session and set process setsid(2 

group ID, foreground process, get tcgetpgrp(3C 

group ID, foreground process, set .tcsetpgrp(3C 

group ID for job control, set process .setpgid(2 

group of processes, send a signal to a process or a kill(2 

gsignal () - raise a software signal ssignal(3C 

gtty(), stty() - control terminal device (Version 6 compatibility only) stty(2 

halt or start auditing system audctl(2 

handler, establish a cleanup .pfm_$cleanup(3i 

handler for this connection, add audio event AtInitialize(3X 

handler, release a cleanup .pfm_$rls_cleanup(3i 

handler, reset a cleanup .pfm_$reset_cleanup(3 

hardware capabilities, check for presence of is_hw_present(3C 

hashing encryption, generate .crypt(3C 

hash search tables, manage Jisearch(3C 

hasmntopt ( ) - search mount option field in file system description file getmntent(3X 

havediskO - get performance data from remote kernel rstat(3N) 

hcreateO - allocate space for new hash search table Y hsearch(3C) 
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hdestroyO - destroy existing hash search table hsearch(3C) 

herror ( ) - resolver routines .resolver(3N) 

hierarchy, directory, recursively descend a ftw(3C) 

hold signal upon receipt sigset(2V) 

host and network byte order, convert values between byteorder(3N) 

host cpu, set name of sethostname(2) 

host CPU, set NetlPC node name of ipcsetnodename(2) 

host, current, get name of gethostname(2) 

host, obtain NetlPC node name of current ipcgetnodename(2) 

HP 3000-mode packed decimal library lippac(3X) 

HP-IB: allow interface to enable SRQ line on HP-IB hpib_rqst_srvce(3l) 

HP-IB: change active controllers on HP-IB hpib_pass_ctl(3l) 

HP-IB: conduct a serial poll on HP-IB hpib_spoll(3I) 

HP-IB: conduct parallel poll on HP-IB hpibj»poll(3I) 

HP-IB: control Attention line on HP-IB hpib_atn_ctl(3l) 

HP-IB: control EOI mode for HP-IB file Jhpib_eoi_ctl(3l) 

HP-IB: control response to parallel poll on HP-IB hpib_card_ppoll_resp(3l) 

HP-IB: control the Remote Enable line on HP-IB hpib_ren_ctl(3l) 

HP-IB: define interface parallel poll response hpib_ppoll_resp_ctl(3l) 

HP-IB: enable/disable odd parity on ATN commands hpib_parity_ctl(3l) 

HP-IB: perform I/O with an HP-IB channel from buffers hpib_io(3l) 

HP-IB: return status of HP-IB interface hpib_bus_status(3l) 

HP-IB: send command bytes over HP-IB hpib_send_cmnd(3l) 

HP-IB: set HP-IB bus address for an interface hpib_address_ctl(3l) 

HP-IB: stop activity on specified HP-IB Jbpib_abort(3l) 

HP-IB: wait until a particular parallel poll value occurs hpib_wait_on_ppoll(3l) 

HP-IB: wait until the requested status condition becomes true hpib_status_wait(3l) 

hpib_abort ( ) - stop activity on specified HP-IB hpib_abort(3l) 

bpib_address_ctl ( ) - set HP-IB bus address for an interface hpib_address_ctl(3l) 

hpib_atn_ctl() - control Attention line on HP-IB hpib_atn_ctl(3l) 

HP-IB bus address for an interface, set hpib_address_ctl(3l) 

hpib_bus_status ( ) - return status of HP-IB interface hpib_bus_status(3l) 

hpib_card_ppoll_resp ( ) - control response to parallel poll on HP-IB hpib_cardjppoll_resp(3l) 

hpib_eoi_ctl ( ) - control EOI mode for HP-IB file hpib_eoi_ctl(3l) 

HP-IB/GPIO/parallel channel, perform low-overhead I/O on an io_burst(3l) 

hpib_io() -perform I/O with an HP-IB channel from buffers hpib_io(3l) 

hpib_parity_ctl ( ) - enable/disable odd parity on ATN commands hpib_parity_ctl(3l) 

hpib_pass_ctl ( ) - change active controllers on HP-IB hpibjpass_ctl(3l) 

bpib_ppoll() - conduct parallel poll on HP-IB hpibj>poll(3l) 

hpib_ppoll_resp_ctl ( ) - define interface parallel poll response hpibjjpoll_resp_ctl(3I) 

hpib_ren_ctl ( ) - control the Remote Enable fine on HP-IB hpib_ren_ctl(3l) 

hpib_rqst_srvce ( ) - allow interface to enable SRQ line on HP-IB hpib_rqst_srvce(3l) 

hpib_send_cmnd( ) - send command bytes over HP-IB hpib_send_cmnd(3l) 

hpib_spoll() - conduct a serial poll on HP-IB hpib_spoll(3l) 

hpib_status_wait ( ) - wait until the requested status condition becomes true hpib_status_wait(3l) 

bpib_wait_on_ppoll ( ) - wait until a particular parallel poll value occurs hpib_wait_on_ppoll(3l) 

HPPAC*: HP 3000-mode packed decimal library hppac(3X) 

hsearchO -hash table search routine hsearch(3C) 

htonl ( ) - convert values between host and network byte order byteorder(3N) 

htons ( ) - convert values between host and network byte order byteorder(3N) 

hyperbolic trigonometric functions, inverse asinh(3M) 

hyperbolic trigonometric functions jsinh(3M) 

hypotenuse of a right triangle Jhypot(3M) 

hypot ( ) - Euclidean distance function hypot(3M) 

iconv, iconvi, iconv2 - code set conversion routines iconv(3C) 

iconvsize ( ) , iconvopen( ) , iconvclose ( ) , iconvlock ( ) - code set conversion routines iconv(3C) 

ID, create session and set process group setsid(2) 

ID, foreground process group, get tcgetpgrp(3C) 
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ID, foreground process group, set .tcsetpgrp(3C) 

ID for job control, set process group .setpgid(2) 

ID, get real or effective user or group getuid(2) 

ID of local machine, get diskless cnode cnodeid(2) 

ID, set user or group setuid(2) 

ID to file path, map device devnm(3) 

idtolang( ) - convert NLS language ID number to language name langinfo(3C) 

ignorable signals mask, set current sigsetmask(2) 

ignore signal sigset(2V) 

ignore signals sigblock(2) 

in-core state with its state on disk, synchronize a file's fsync(2) 

increase data segment space allocation .brk(2) 

index () -BSD portability string routine string(3C) 

inet_addr () -Internet address manipulation routines inet(3N) 

inet_lnaof ( ) - Internet address manipulation routines inet(3N) 

inet_makeaddr ( ) - Internet address manipulation routines inet(3N) 

inet_netof ( ) - Internet address manipulation routines inet(3N) 

inet_network ( ) - Internet address manipulation routines inet(3N) 

inet_ntoa () - Internet address manipulation routines inet(3N) 

INFINITY, test for isinf(3M) 

information about users on remote machines, return rnusers(3N) 

information, access exported file system exportent(3N) 

information, NLS, about native languages langinfo(3C) 

information, NLS, about native languages nl_langinfo(3C) 

inhibit asynchronous faults; allow time-sliced task switching pfm_$inhibit_faults(3) 

inhibit asynchronous faults .pfm_$inhibit(3) 

initgroups ( ) - initialize group access list initgroups(3C) 

initialize group access list initgroups(3C) 

initiaHze, manipulate, and test signal sets sigsetops(3C) 

initiaUze NetlPC option buffer initopt(3N) 

initialize semaphore in mapped file or anonymous memory region msem_init(2) 

initiaUze the NLS environment of a program nl_init(3C) 

initiaUze the process fault manager package pfm_$init(3) 

initiate an audio widget play operation AuInvokePlay(3X) 

initiate an audio widget record operation AuInvokeRecord(3X) 

initiate connection on a socket connect(2) 

initiate transaction and return transaction ID and SStream structure APlaySStream(3X) 

initiate transaction; return transaction ID and SStreams structure ARecordSStream(3X) 

initopt () -initialize NetlPC option buffer initopt(3N) 

innetgr ( ) - get network group entry getnetgrent(3C) 

input conversion, formatted read from stream file or character string scanf(3S) 

input conversion, formatted, to a varargs argument vscanf(3S) 

input/output, buffered, standard stream file package stdio(3S) 

input/output to a stream file, buffered binary fread(3S) 

input stream, push character back into ungetc(3S) 

input stream, push wide character back into ungetwc(3C) 

input string from a standard input stream gets(3S) 

input wide string from a standard input stream getws(3C) 

integer absolute value, return .abs(3C) 

integer, convert string to long strtol(3C) 

integer, convert wide character string to long wcstol(3C) 

integer data in a machine-independent fashion, access long sputl(3X) 

integer division and remainder div(3C) 

integer, long, convert to string, ltostr(3C) 

integers, convert between 3-byte integers and long integers l3tol(3C) 

integer to base-64 ASCII string, convert long a64l(3C) 

interface: define HP-IB interface parallel poll response hpib_ppoIl_resp_ctl(3l) 

interface, control DMA aUocation for an io_dma_ctl(3l) 
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interface, GPIO: return status lines of GPIO card gpio_get_status(3l) 

interface, GPIO: set control lines on GPIO card gpio_set_ctl(3l) 

interface, HP-IB: allow interface to enable SRQ line on HP-IB hpib_rqst_srvce(3l) 

interface, HP-IB: change active controllers on HP-IB hpib_pass_ctl(3l) 

interface, HP-IB: conduct a serial poll on HP-IB hpib_spoll(3I) 

interface, HP-IB: conduct parallel poll on HP-IB hpib_ppoll(3l) 

interface, HP-IB: control EOI mode for HP-IB file bpib_eoi_ctl(3l) 

interface, HP-IB: control response to parallel poll on HP-IB hpib„cardj?poll_resp(3l) 

interface, HP-IB: control the HP-IB interface Remote Enable line hpib_ren_ctl(3l) 

interface, HP-IB: perform I/O with an HP-IB channel from buffers hpib_io(3I) 

interface, HP-IB: return status of HP-IB interface hpib_bus_status(3l) 

interface, HP-IB: send command bytes over HP-IB hpib_send_cmnd(3l) 

interface, HP-IB: stop activity on specified HP-IB hpib_abort(3I) 

interface, HP-IB: wait until a particular parallel poll value occurs hpib_wait_on_ppoll(3l) 

interface, HP-IB: wait until the requested status condition becomes true hpib_status_wait(3l) 

interface, Network Information Service client ypclnt(3C) 

interface parallel poll response, define hpib_ppoU_resp_ctl(3l) 

interface, reset an I/O io_reset(3l) 

interface, set HP-IB bus address for an hpib_address_ctl(3l) 

interface, unlock or lock an I/O io_lock(3l) 

interleaved paging/swapping, add a swap device for swapon(2) 

Internet address manipulation routines inet(3N) 

interprocess channel, create an .pipe (2) 

interprocess communication package, standard stdipc(3C) 

interrupt, atomically release blocked signals and wait for sigpause(2) 

interrupt (fault) conditions, define for I/O device io_on_interrupt(3l) 

interrupts for the associated eid(), disable or enable I/O io_interrupt_ctl(3l) 

interval, suspend execution for .sleep(3C) 

interval timer, set or get value of process getitimer(2) 

introduction to subroutines and libraries intro(3) 

introduction to system calls intro(2) 

intro ( ) - introduction to subroutines and libraries intro(3) 

inverse hyperbolic trigonometric functions asinb(3M) 

I/O: GPIO card, return status fines of gpio_get_status(3I) 

I/O: GPIO card, set control fines on gpio_set_ctl(3l) 

io_burst ( ) - perform low-overhead I/O on an HP-IB/GPIO/parallel channel io_burst(3l) 

I/O, control character device special file ioctl(2) 

ioctl ( ) - control character device special file ioctl(2) 

I/O data path width (in bits), set io_width_ctl(3l) 

I/O device interrupt (fault) control io_on_interrupt(3l) 

io_dma_ctl ( ) - control DMA allocation for an interface io_dma_ctl(3l) 

io_eol_ctl () - set up I/O read termination character on special file io_eol_ctl(3l) 

io_get_term_reason( ) - determine how last read terminated io_get_term_reason(3l) 

I/O interface, reset an io_reset(3l) 

I/O interface, unlock or lock an io_lock(3l) 

io_interrupt_ctl ( ) - enable/disable interrupts for the associated eid ( ) io_interrupt_ctl(3l) 

I/O interrupts for the associated eid( ) , disable or enable io_interrupt_ctl(3l) 

io_lock ( ) , io_unlock ( ) - lock and unlock an I/O interface io_lock(3l) 

I/O multiplexing, synchronous select (2) 

I/O on an HP-IB/GPIO/parallel channel, perform low-overhead io_burst(3l) 

io_on_interrupt ( ) - device I/O interrupt (fault) control io_on_interrupt(3l) 

I/O operations on a stream file, get or reposition pointer for fseek(3S) 

I/O operations, set time limit for io_timeout_ctl(3l) 

I/O pipe to or from a process, open or close .popen(3S) 

I/O read, determine how last terminated io_get_term_reason(3l) 

I/O read termination character on special file, set up io_eol_ctl(3l) 

io_reset ( ) - reset an I/O interface io_reset(3l) 

io_speed_ctl ( ) -inform system of required transfer speed io_speed_ctl(3l) 
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IOT fault, generate an abort(3C 

io_timeout_ctl ( ) - establish a time limit for I/O operations io_timeout_ctl(3r 

I/O to a stream file, buffered binary fread(3& 

io_unlock() - unlock an I/O interface io_lock(3L 

io_width_ctl ( ) — set width (in bits) of data mth .............................,......=...............,..,..,,. io_width_ctl(3l 

I/O with an HP-IB channel from buffers, perform hpib_io(3l 

ipcconnect ()()- request connection to another process ipcconnect(2i 

ipccontrol()()- perform special operations onNetlPC sockets ipccontrol(2 

ipccreate ()()- create a call socket ipccreate(2i 

ipcdest () - create a destination descriptor ipcdest(2 

ipeerrmsgO -provide text describing NetlPC error number ipcerrmsg(3N) 

ipcgetnodename ( ) - obtain NetlPC node name of current host ipcgetnodename(2 

ipclookup()()- obtain a destination descriptor ipclookup(2 

ipcname ( ) () - associate name with call socket or destination call socket ipcname(2' 

ipcnamerase ( ) () - delete name associated with a call socket or destination call socket ipcnamerase(2 

ipcrecvcnOO- receive connection request on a call socket ipcrecvcn(2 

ipcrecv( ) () - establish or receive data onNetlPC virtual circuit connection ipcrecv(2 

ipcselect ( ) () - determine status of call socket or VC socket ipcselect(2 

ipcsend ( ) () - send data on a virtual circuit connection ipcsend(2 

ipcsetnodename ( ) -set NetlPC node name of host CPU ipcsetnodename(2' 

ipc shutdown ( )() -release a descriptor ipcshutdown(2 

IP port, bind socket to a privileged bindresvport(3N) 

is_68010_present() - check for MC68010 system microprocessor is_hw_present(3C 

is_68881_present() - check for MC68881 math coprocessor is_hw_present(3C 

is_98248A_present () - check for floating-point accelerator card is_hw_j>resent(3C 

is_98635A_present ( ) - check for floating-point math card is_hw_present(3C 

isalnum( ) - character is alphanumeric ctype(3C 

isalpha ( ) - character is alpha .ctype(3C 

isascii ( ) - character is 7-bit ASCII code ctype(3C 

isascii - character is 7-bit ASCII code wctype(3C 

isattyO - find name of a terminal ttyname(3Q 

iscntrl ( ) - character is a control character ctype(3C 

isdigit ( ) - character is a digit .ctype(3C 

isgraphO -character is a visible character ctype(3C 

isinf f ( ) , isinf - test for INFINITY isinf(3M) 

isinf ( ) , isinf f - test for INFINITY isinf(3M) 

islower ( ) - character is lowercase .ctype(3C 

isnanf (), isnanO -test for NaN isnan(3M 

isnan(), isnanf () -test for NaN isnan(3M 

isprint ( ) - character is a printing character ctype(3C 

ispunct ( ) - character is punctuation ctype(3C 

isspace ( ) - character is whitespace ctype(3C 

issue a shell command system(3& 

isupper ( ) - character is uppercase .ctype(3C 

iswalnum- character is alphanumeric wctype(3C 

iswalpha- character is alpha .wctype(3C 

iswcntrl - character is a control character wctype(3C 

iswdigit - character is a digit .wctype(3C 

iswgraph- character is a visible character wctype(3C 

iswlower - character is lowercase wctype(3C 

iswprint - character is a printing character wctype(3C' 

iswpunct - character is punctuation wctype(3C 

iswspace - character is whitespace wctype(3C 

iswupper- character is uppercase wctype(3C 

iswxdigit - character is a hexadecimal digit wctype(3C 

isxdigit ( ) - character is a hexadecimal digit ctype(3C 

J ( ) , j 1 ( ) , jn( ) , yO ( ) , yl ( ) , yn ( ) - Bessel functions bessel(3M) 

j 1 ( ) - Bessel function .bessel(3M) 
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jn() -Bessel function .bessel(3M) 

job control, set process group ID for .setpgid(2) 

keep track of remotely mounted file systems mount(3N) 

kernel, remote, get performance data from rstat(3N) 

killpgO - 4.2 BSD-compatible kill ( ) system call bsdproc(2) 

kill ( ) , raise ( ) - send signal to process or group of processes kill(2) 

kill ( ) system call, 4.2 BSD-compatible .bsdproc(2) 

13tol ( ) - convert 3-byte integer to long integer l3tol(3C) 

164a () - convert long integer to base-64 value ASCII string a64l(3C) 

labs ( ) - return long integer absolute value abs(3C) 

langinf o ( ) - obtain NLS string form of local language variable langinfo(3C) 

langtoid( ) - convert NLS language name to language ID number langinfo(3C) 

languages, NLS information about native (local) langinfo(3C) 

languages, NLS information about native (local) nl_langinfo(3C) 

last I/O read, determine how terminated io_get_term_reason(3l) 

last locations of allocated regions in program end(3C) 

ldecvt ( ) , (_ldecvt ( ) ) - convert long double to string ldcvt(3C) 

_ldecvt ( ) , _ldf cvt ( ) , _ldgcvt ( ) - convert long double to string ldcvt(3C) 

ldexp ( ) , f rexp ( ) , modf ( ) - split floating-point into mantissa and exponent frexp(3C) 

ldf cvt ( ) , (_ldf cvt ( ) ) - convert long double to string ldcvt(3C) 

ldgcvt (), (_ldgcvt ())- convert long double to string ldcvt(3C) 

ldiv( ) - long integer division and remainder div(3C) 

legal user shells, get .get user shell (3C) 

length of string, find string(3C) 

length of wide string, find .wcstring(3C) 

IgammaO, gamma(), signgamO -log gamma function gamma(3M) 

libraries and subroutines, introduction to intro(3) 

library, packed decimal, HP3000-mode Jippac(3X) 

library routines for external data representation xdr(3C) 

library routines for remote procedure calls xpc(3C) 

limit for I/O operations, set time io_timeout_ctl(3l) 

limit, get or set system resource consumption getrlimit(2) 

linear table search with optional update lsearch(3C) 

line connection, establish an out-bound terminal dial(3C) 

line control functions, tty .tccontrol(3C) 

line on HP-IB, control the Remote Enable hpib_ren_ctl(3l) 

lines of GPIO card, return status gpio_get_status(3l) 

lines on GPIO card, set control gpio_set_ctl(3l) 

line, SRQ, on HP-IB, allow interface to enable hpib_rqst_srvce(3l) 

link ( ) - link additional name to an existing file link(2) 

link, symbolic, read value of readlink(2) 

link to a file, make a symbolic .symlink(2) 

listen for connections on a socket listen (2) 

listen() - listen for connections on a socket listen (2) 

list, get group access getgroups(2) 

list, initialize group access initgroups(3C) 

list, name, get entries from nlist(3C) 

list, print formatted output of a varargs argument vprintf(3S) 

list, set group access setgroups(2) 

load shared library shl_load(3X) 

localeconv( ) - query numeric formatting conventions of current locale localeconv(3C) 

locale, current, query numeric formatting conventions of localeconv(3C) 

locale of a program, get or set the setlocale(3C) 

local machine, get diskless cnode ID of cnodeid(2) 

local (native) languages, NLS information about langinf o(3C) 

local (native) languages, NLS information about nl_langinfo(3C) 

local time ( ) - convert date and time to local timezone ctime(3C) 

location of character in memory, find memory(3C) 
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locations beyond allocated program regions, first end(3C) 

lock a semaphore msem_lock(2) 

lockf ( ) - provide semaphores and record locking on files lockf(2) 

locking on files, provide semaphores and record lockf(2) 

lock or "unlock an I/O interface io_lock(3l) 

lock process into memory after allocating data and stack space datalock(3C) 

lock process, text, or data in memory .plock(2) 

loglOf (),logf (), log2f (), log(), loglOO, log2() - logarithm functions exp(3M) 

loglOO, log(), log2(), logf (), loglOf (), log2f () - logarithm functions exp(3M) 

log2f (), logf (), loglOf (), log(), loglO ( ) , log2 ( ) - logarithm functions exp(3M) 

log2(), log(), loglOO, logf (), loglOf (), log2f () - logarithm functions exp(3M) 

logarithm, exponential, power, square root, cube root functions exp(3M) 

logb ( ) , scalb ( ) - exponent manipulations ieee(3M) 

logf (), loglOf (), log2f (), log(), loglOO, log2() - logarithm functions exp(3M) 

log gamma function gamma(3M) 

login name in utmp ( ) , get pointer to getlogin(3C) 

login name of the user, get character-string cuserid(3S) 

login name of user, obtain logname(3C) 

log(), loglOO, log2(), logf (), loglOf (), log2f () - logarithm functions exp(3M) 

logname ( ) - return login name of user logname(3C) 

log, system, control syslog(3C) 

long double floating-point number to string, convert ldcvt(3C) 

long double-precision number, convert string to strtold(3C) 

long integer data in a machine-independent fashion, access sputl(3X) 

long integers and 3-byte integers, convert between l3tol(3C) 

long integer to base-64 ASCII string, convert a64l(3C) 

long integer to string, convert ltostr(3C) 

_longjmp ( ) - restore stack environment after non-local goto setjmp(3C) 

look up symbol in shared library shl_load(3X) 

lowercase, translate characters to conv(3C) 

lowercase, translate wide characters to wconv(3C) 

low-overhead I/O on an HP-IB/GPIO/parallel channel, perform io_burst(3l) 

lrand48 ( ) , nrand48 ( ) - generate long-integer pseudo-random numbers drand48(3C) 

lsearch ( ) , If ind ( ) - linear search and update : lsearch(3C) 

lseek ( ) - move read/write file pointer; seek lseek(2) 

lstat ( ) , (atat ( ) , f stat ( ) ) - get file fink status stat(2) 

lsync ( ) , sync ( ) - update super-block sync(2) 

ltoa ( ) ; convert long integer to ASCII decimal ltostr(3C) 

ltol3 ( ) - convert long integer to 3-byte integer l3tol(3C) 

ltostr ( ) ; convert long integer to string ltostr(3C) 

machine, get diskless cnode ID of local cnodeid(2) 

machines, return information about users on remote rnusers(3N) 

machines, write to specified remote .rwall(3N) 

madvise - advise system of process' expected paging behavior madvise(2) 

main memory allocator malloc(3C) 

main memory space allocation, control malloc(3C) 

main memory space usage, display .malloc (3C) 

make a directory file mkdir(2) 

make a directory, or a special or ordinary file mknod(2) 

make a FIFO special file mkfifo(3C) 

make a symbolic fink to a file .symlink(2) 

make a unique (usually temporary) file name mktemp(3C) 

mallinf o( ) - display memory space usage malloc(3C) 

malloc ( ) - allocate block of main memory ma!loc(3C) 

malloc, free ( ) , realloc ( ) , calloc ( ) mallopt ( ) , 

maLlinf o ( ) , memorymap ( ) - main memory allocator malloc(3C) 

mallopt ( ) - control memory space allocation malloc(3C) 

manage a binary search tree .tsearch(3C) 
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manage hash search tables Jhsearch(3C 

management, program .pgm_$intro(3 

management, signal (sigsetO, sigholdO, sigrelse(), sigignore(), sigpauseO) sigset(2V) 

managing signal exceptions .pfm_$intro(3 

manipulate disk quotas .quotactl(2 

manipulate, initialize, and test signal sets sigsetops(3C 

manipulation routines, Internet address inet(3N) 

mantissa and exponent, split floating-point into frexp(3C 

map device ID to file path .devnm(3i 

map object into virtual memory jnmap(2 

mapped file or anonymous memory region, initialize semaphore in msem_init(2 

mapped file or anonymous region, remove semaphore in msem_remove(2i 

mapped file, synchronize a jnsync(2^ 

mapped region, unmap a munmap(2 

mapping access protections, modify memory mprotect(2' 

map stream pointer to file descriptor fQeno(3S^ 

mask for file creation, set and get permissions umask(2 

mask, set current ignorable signals sigsetmask(2 

match filename patterns fnmatch(3C 

matching routines, regular expression xegcomp(30 

match routines for regular expressions xegexp(3X] 

math: Bessel functions .bessel(3M) 

math: complex absolute value function hypot(3M) 

math: copysign, remainder, classification, exponent manipulations ieee(3M! 

math: error function and complementary error function erf(3M! 

math: Euclidean distance (hypotenuse) function hypot(3M) 

math: exponential, logarithm, power, square root, cube root functions exp(3M. 

math: floating-point classification functions fpclassify(3M] 

math: floating-point mode control functions fpgetround(3Mi 

math: floor, ceiling, remainder, absolute value, round-to-nearest functions floor(3M) 

math: hyperbolic trigonometric functions sinh(3M 

math: inverse hyperbolic trigonometric functions asinh(3M' 

math: log gamma function gamma(3M 

math: math library error-handling function matherr(3M! 

math: split floating-point into mantissa and exponent frexp(3C 

math: test for INFINITY isinf(3M) 

math: test for NaN isnan(3M 

math: trigonometric functions (degrees) trigd(3M! 

math: trigonometric functions .trig(3M' 

math coprocessor or accelerator, check for presence of is_hw_jxresent(3C 

matherrO - math library error-handling function matherr(3M! 

math library error-handling function matherr(3M! 

mblen( ) - multibyte characters and strings conversions multibyte(3Q 

mbstowcs ( ) - multibyte characters and strings conversions multibyte(3C 

mbtowc ( ) - multibyte characters and strings conversions multibyte(3C 

mcrtO.o, crtO.o- C and Pascal execution startup routines crt0(3 

memchrO - find first occurrence of character in memory area memory(3C 

memcmpO - compare character with memory contents memory(3C 

memcpyO, memccpyO - copy characters from memory to another memory location memory(3C 

memmove ( ) - move memory contents memory(3C 

memory allocator for main memory jnalloc(3C 

memory control operations, shared .shmctl(2 

memory, lock process into after allocating data and stack space datalock(3C 

memory, lock process, text, or data in plock® 

memorymapO - display contents of memory allocator malloc(3C 

memory, map object into virtual jnmap(2 

memory mapping access protections, modify mprotect(2' 

memory operations - copy, compare, test for contents, or set contents to value memory(3C 
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memory region, initialize semaphore in mapped file or anonymous msem_init(2) 

memory segment, get shared shmget(2) 

memset ( ) - set area in memory to contain a specified character memory(3C) 

message catalog for reading, close or open NLS catopen(3C) 

mogcoco r>afaln<T siimmrt. PTT?./MPl?.e!+\rlo r»nt.***»8'1f3CTl 

message catalogue, get message from an NLS catgetmsg(3C) 

message control operations jnstctl(2) 

message for a status code, return an error error_$c_text(3) 

message from an NLS message catalogue, get catgetmsg(3C) 

message from a socket, receive , recv(2) 

message, NLS program, get an ,,,. ,,„..catgets(3C) 

message queue, get msgget(2) 

message, send or receive message to or from message queue msgop(2) 

message, send to a socket send(2) 

messages, system error .perror(3C) 

mf rtO . o, f rtO . o - Fortran execution startup routines crt0(3) 

microprocessor, MC68010, check for presence of is_hw_present(3C) 

minimum I/O data transfer rate, inform system of required io_speed_ctl(3l) 

mkdir ( ) - make a directory file jnkdir(2) 

mkf if o ( ) - make a FIFO special file mkfifo(3C) 

mknodO -make a directory, or a special or ordinary file mknod(2) 

mkrnodO - make a cnode-specific special file mknod(2) 

mktemp ( ) - make a unique (temporary) file name mktemp(3C) 

mktimeO - convert time into calendar time value ctime(3C) 

mktimer - allocate a per-process timer mktimer(3C) 

mmap - map object into virtual memory mmap(2) 

mode, EOI, for HP-IB file, control lipib_eoi_ctl(3l) 

mode (permissions) of file, change access chmod(2) 

modf ( ) , f rexp ( ) , ldexp ( ) - split floating-point into mantissa and exponent frexp(3C) 

modification and access times, set or update file utime(2) 

modify, add, or delete access control fist entry setaclentry(3C) 

modify memory mapping access protections mprotect(2) 

module, and error texts for a status code, return subsystem, error_$c_get_text(3) 

monitor audio channel gain, get system or AGetSystemChannelGain(3X) 

monitor audio channel gain, set system or ASetSystemChannelGain(3X) 

monitor I/O conditions on multiple file descriptors poll(2) 

monitor ( ) - prepare execution profile monitor(3C) 

mount (): keep track of remotely mounted file systems mount(3N) 

mount a file system .vfsmount(2) 

mount a removable file system .mount (2) 

mounted file systems, keep track of remotely mount(3N) 

mounted file system statistics, get .ustat(2) 

mount ( ) - mount a removable file system mount (2) 

move read/write file pointer; seek lseek(2) 

MPE clock value, return the .clock(3X) 

MPE Native Language Support: 

append language ID to valid MPE file name nlappend(3X) 

check/convert time string to MPE internal format nlconvclock(3X) 

compare character arrays (keyl, key2) using MPE collation table nlkeycompare(3X) 

compare strings; use MPE language-dependent collating sequence nlcollate(3X) 

convert ASCII number to MPE language-specific formatted number nlfmtnum(3X) 

convert date string to MPE packed date format nlconvcustdate(3X) 

convert MPE native language formatted number to ASCII nlconvnum(3X) 

convert string between phonetic and screen order u sing MPE table nls witchbuf (3X) 

extract substring in string using MPE character set table nlsubstr(3X) 

format MPE date and time in localized format nlfmtdate(3X) 

format MPE packed date using custom date nlfmtcustdate(3X) 

format MPE packed date using localized format nlfmtcal(3X) 
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format MPE packed date using long calendar format nlfmtlongcal(3X) 

format MPE time of day using localized format nlfmtclock(3X) 

identify one- or multi-byte Asian character using MPE character table nljudge(3X) 

move, scan, case-shift strings using MPE character set table nlscanmove(3X) 

replace non-displayable string characters using MPE character set table nlrepchar(3X) 

return current user, data, or system default language nlgetlang(3X) 

return MPE calendar date calendar(3X) 

return MPE language-dependent information *slinfo(3X) 

return number conversion/formatting information for MPE routines nlnumspec(3X) 

return numeric date information in MPE format almanac(3X) 

search for string in a string using MPE character set definition nlfindstr(3X) 

translate ASCII strings to EBCDIC using MPE conversion table nltranslate(3X) 

MPE/RTE-style message catalog support catread(3C) 

mprotect - modify memory mapping access protections mprotect(2) 

mrand48 ( ) , jran&48 ( ) - generate signed long-integer pseudo-random numbers drand48(3C) 

msem_init - initialize semaphore in mapped file or anonymous memory region msem_init(2) 

msem_lock - lock a semaphore msem_lock(2) 

msem_remove - remove semaphore in mapped file or anonymous region msem_remove(2) 

msem_unlock - unlock a semaphore msem_uiilock(2) 

msgctl ( ) - message control operations mstctl(2) 

msgget ( ) - get message queue jmsgget(2) 

msgrcvO -receive message from message queue msgop(2) 

msgsnd ( ) - send message to message queue msgop(2) 

msync - synchronize a mapped file msync(2) 

multibyte characters and strings conversions multibyte(3C) 

multiplexing, synchronous I/O select(2) 

munmap - unmap a mapped region munmap(2) 

name: 

change the name of a file xename(2) 

create a name for a temporary file tmpnam(3S) 

find name of a terminal .ttyname(3C) 

get character-string representation of user login name cuserid(3S) 

get entries from name list jilist(3C) 

get name and version of current HP-UX system uname(2) 

get name from UID (obsolete) .getpw(3C) 

get name of current host gethostname(2) 

get pointer to login name in utmp ( ) getlogin(3C) 

obtain user login name logname(3C) 

set the name of host cpu sethostname(2) 

name associated with a call socket or destination call socket, delete ipcnamerase(2) 

name, associate with call socket or destination call socket ipcname(2) 

name, get disk description by its getdiskbyname(3C) 

name of a slave pty, get the ptsname(3C) 

name of current host, obtain NetlPC node ipcgetnodename(2) 

name of current NIS domain, get or set getdomainname(2) 

name of host CPU, set NetlPC node ipcsetnodename(2) 

names, manipulate context-dependent file path getcdf(3C) 

NaN, test for isnan(3M) 

native languages, NLS information about langinfo(3C) 

native languages, NLS information about nl_langinfo(3C) 

net_aton( ) - network station address string conversion routines , net_aton(3C) 

NetlPC error number, provide text describing ipcerrmsg(3N) 

NetlPC node name of current host, obtain ipcgetnodename(2) 

NetlPC node name of host CPU, set ipcsetnodename(2) 

NetlPC option buffer, add argument and data to addopt(3N) 

NetlPC option buffer, initialize initopt(3N) 

NetlPC option buffer, obtain option code and data from readopt(3N) 

NetlPC option, return number of bytes needed by a optoverhead(3N) 
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NetlPC sockets, perform special operations on ipccontrol(2) 

NetlPC virtual circuit connection, establish or receive data on ipcrecv(2) 

net_ntoa ( ) - network station address string conversion routines net_aton(3C) 

network and host byte order, convert values between byteorder(3N) 

network entry, get or set getnetent(3N) 

network group entry, get or set getnetgrent(3C) 

network host entry, get or set .gethostent(3N) 

Network Information Service client interface ypclnt(3C) 

Network Information Service, update user password in yppasswd(3N) 

network, scatter data to check the .spray(3N) 

network station address string conversion routines net_aton(3C) 

new file, create creat(2) 

new process, create a fork(2) 

nextkey ( ) - get next key in database (old single-data-base version) dbm(3X) 

NFS daemons nfssvc(2) 

nf ssvc ( ) : NFS daemon nfssvc(2) 

nice() - change priority of a process Jiice(2) 

NIS domain, get or set name of current getdomainname(2) 

nlappend ( ) - append language ID to valid MPE file name nlappend(3X) 

nl_atof ( ) - convert string to double-precision number strtod(3C) 

nlcollate ( ) - compare strings; use MPE language-dependent collating sequence nlco!late(3X) 

nlconvclockO - check/convert time string to MPE internal format nlconvclock(3X) 

nlconvcustdate ( ) - convert date string to MPE packed date format nlconvcustdate(3X) 

nlconvnum( ) - convert MPE native language formatted number to ASCII nlconvnum(3X) 

nl_ctime ( ), nl_asctime ( ) - (obsolete; backwards compatibility only) ctime(3C) 

nlf indstr ( ) - search for string in a string using MPE character set definition nMndstr(3X) 

nlfmtcalendar ( ) - format MPE packed date using localized format nlfmtcal(3X) 

nlfmt clock ( ) -format MPE time of day using localized format nlfmtclock(3X) 

nlfmtcustdate ( ) - format MPE packed date using custom date nlfmtcustdate(3X) 

nlfmtdateO -format MPE date and time in localized format nIfmtdate(3X) 

nl f mt longcal ( ) - format MPE packed date u sing long calendar format nlf mtlongcal(3X) 

nl£mtnum( ) - convert ASCII number to MPE language-specific formatted number nlfmtnum(3X) 

nl_f print f () , fprintf ( ) - print formatted output to a file printf(3S) 

nl_fscanf (), fscanf - formatted read from named input stream file scanf(3S) 

nl gcvt ( ) , gcvt ( ) - convert floating-point number to string array element ecvt(3C) 

nlgetlang ( ) - return current user, data, or system default language nlgetlang(3X) 

nlinf o ( ) - return MPE language-dependent information nlinfo(3X) 

nl_init ( ) , langinit ( ) (obsolete) - initialize the NLS environment of a program nl_init(3C) 

nl_isalnum() - NLS character class is alphanumeric nl_ctype(3C) 

nl_isalpha ( ) - NLS character class is alpha nl_ctype(3C) 

nl_iscntrl() -NLS character class is a control character nl_ctype(3C) 

nl_isdigit () - NLS character class is a digit nl_ctype(3C) 

nl_isgraph() - NLS character class is a visible character nl_ctype(3C) 

nl_islower ( ) - NLS character class is lowercase nl_ctype(3C) 

nl_isprint () -NLS character class is a printing character nl_ctype(3C) 

nl_ispunct () - NLS character class is punctuation nl_ctype(3C) 

nl_isspace ( ) - NLS character class is whitespace nl_ctype(3C) 

nlist () - get entries from name list nlist(3C) 

nl_isupper ( ) - NLS character class is uppercase nl_ctype(3C) 

nl_isxdigit ( ) - NLS character class is a hexadecimal digit nl_ctype(3C) 

nl judge ( ) - identify one- or multi-byte Asian character using MPE character table nljudge(3X) 

nlkeycompare ( ) - compare character arrays using MPE collation table nlkeycompare(3X) 

nl_langinf o ( ) - obtain NLS string form of local language variable nl_langinfo(3C) 

nlnumspec () - return number conversion/formatting information for MPE routines nlnumspec(3X) 

nl_printf () , printf ( ) - print formatted output to standard output printf(3S) 

nlrepchar () - replace non-displayable string characters using MPE character set table nlrepchar(3X) 

NLS: classify characters for use with NLS nl_ctype(3C) 

NLS: get an NLS program message, .catgets(3C) 
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NLS: get message from an NLS message catalogue catgetmsg(3C 

NLS: initialize NLS environment of a program nl_init(3C' 

NLS: NLS information about native languages langinfo(3C 

NLS: NLS information about native languages nl_langinfo(3C 

NLS: open or close message catalog for reading catopen(3C 

NLS: query numeric formatting conventions of current locale localeconv(3C 

NLS: translate characters for use with NLS (obsolete - useconv( ) (3C)) nl_conv(3C 

nLsoanf ( ) , scanf ( ) - formatted read from standard input stream file scanf(3S 

nlscanmove ( ) - move, scan, case-shift strings using MPE character set table nlscanmove(3X 

NLS message catalog, open or close for reading catopen(3C 

nl_sprintf ( ) , sprintf ( ) - print formatted output to a string printf(3S' 

nl_sscanf ( ) , s scanf ( ) - formatted read from character string scanf(3Si 

nl_atrcmp ( ) , nl_strncmp ( ) - compare strings using language-dependent collation string(3C 

nl_strtod() - convert string to double-precision number strtod(3C 

nlsubstrO - extract substring in string using MPE character set table nlsubstr(3X 

nlswitchbuf ( ) - convert string between phonetic and screen order using MPE table nlswitchbuf(3X 

nl_toupper ( ) , nl_tolower ( ) - (obsolete) translate characters for use with NLS nl_conv(3C 

nltranslate ( ) - translate ASCII strings to EBCDIC using MPE conversion table nltranslate(3X 

node from a binary search tree, delete a tsearch(3C 

node name of current host, obtain NetlPC ipcgetnodename(2 

node name of host CPU, setNetlPC ipcsetnodename(2' 

non-ASCII string collation jil_string(3C 

non-local goto, save/restore stack environment for setjmp(3C 

ntohl ( ) - convert values between host and network byte order byteorder(3N) 

ntohs ( ) - convert values between host and network byte order byteorder(3N) 

NULL, set callback to AtRemoveCallback(3X 

number, convert string to double-precision strtod(3C 

number, convert string to floating-point cvtnum(3C 

number, convert string to long double-precision strtold(3C 

number, convert wide character string to double-precision wcstod(3C 

number, provide text describing NetlPC error ipcerrmsg(3N) 

numbers, generate uniformly distributed pseudo-random drand48(3C 

number to string, convert long double floating-point ldcvt(3C 

number to string or string array element, convert floating-point ecvt(3C 

numeric formatting conventions of current locale, query localeconv(3C 

object-code file, execute an «xec(2 

object into virtual memory, map jnmap(2 

obtain a destination descriptor ipclookup(2' 

odd parity on ATN commands, enable/disable hpib_parity_ctl(3I) 

open, access, or close a directory directory(3C 

open a directory and associated directory stream for access directory(3C 

open connection to specified audio server AOpenAudio(3X' 

opendirO -open a directory and associated directory stream for access directory(3C 

open-file control fcntl(2 

open file descriptor, duplicate an dup(2' 

open file descriptorto a specific slot, duplicate an dup2(2 

openlogO -initialize system log file syslog(3C 

open ( ) - open file for reading or writing .open(2' 

open or close NLS message catalog for reading catopen(3C 

open or close pipe I/O to or from a process .popen(3S 

open or re-open a stream file; convert file to stream fopen(3S' 

operations, message control jnstctl(2 

operations on a stream file, get or reposition pointer for I/O fseek(3S 

operations on NetlPC sockets, perform special ipccontrol(2 

operations, semaphore control semctl(2' 

operations, semaphore semop(2 

operations, set time limit for I/O io_timeout_ctl(3l 

operations, shared memory control .sbjnctl(2 
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optarg, optind, opterr - get option letter from argument vector getopt(3C) 

optimization package, CRT screen handling and curses(3X) 

option buffer, add argument and data to NetlPC addopt(3N) 

option buffer, initialize NetlPC initopt(3N) 

option buffer, obtain option code and data from NetlPC readopt(SN) 

option code and data from NetlPC option buffer, obtain readopt(3N) 

option letter from argument vector, get getopt(3C) 

options on sockets, get or set .getsockopt(2) 

options, parse suboptions from a string getsubopt(3C) 

optoverhead ( ) - return number of bytes needed by a NetlPC option optoverhead(3N) 

order of data, convert string „,.,.„„...,.... ■. strord(3C) 

ordinary file, make a directory, or a special or mknod(2) 

out-bound terminal line connection, establish an dial(3C) 

output, formatted, print to standard output, file, or string printf(3S) 

output, formatted with numbered arguments, print to a file or string printmsg(3C) 

output/input, buffered, standard stream file package stdio(3S) 

output of a varargs argument list, print formatted vprintf(3S) 

owner and group of a file, change chown(2) 

owner and/or group, change in access control fist (ACL) chownacl(3C) 

package, standard interprocess communication stdipc(3C) 

packed decimal library, HP3000-mode Jbppac(3X) 

paging behavior, advise system of process' expected madvise(2) 

paging/swapping, add a swap device for interleaved swapon(2) 

parallel channel, perform low-overhead I/O on a io_burst(3l) 

parallel poll on HP-IB bus, conduct Jipib_ppoll(3l) 

parallel poll on HP-IB, control response to hpib_card_ppoll_resp(3l) 

parallel poll response, define interface hpibjppoll_resp_ctl(3l) 

parallel poll value occurs, wait until a particular hpib_wait_on_ppoll(3l) 

parent process ID, get process, process group, or getpid(2) 

parity on ATN commands, enable/disable odd hpibj>arity_ctl(3l) 

parse suboptions from a string getsubopt(3C) 

particular parallel poll value occurs, wait until a hpib_wait_on_ppoll(3l) 

Pascal and C execution startup routines .crt0(3) 

password encryption function .crypt(3C) 

password file entry, secure, write .putspwent(3C) 

password file entry, write putpwent(3C) 

password file, get entry from .getpwent(3C) 

password inNetwork Information Service, update user yppasswd(3N) 

password, read from terminal while suppressing echo getpass(3C) 

pathconf ( ), fpathconf ( ) - get configurable pathname variables pathconf(2) 

path, map device ID to file devnm(3) 

path-name of current working directory, get getcwd(3C) 

path names, manipulate context-dependent file getcdf(3C) 

pathname variables, get configurable .pathconf (2) 

patterns, match filename fnmatch(3C) 

pause ( ) - suspend process until signal .pause(2) 

pause the specified audio transaction APauseAudio(3X) 

pclose ( ) - terminate pipe I/O to or from a process popen(3S) 

peer, get address of connected getpeername(2) 

pending signals, examine sigpending(2) 

performance data from remote kernel, get rstat(3N) 

perform I/O with an HP-IB channel from buffers hpib_io(3l) 

perform low-overhead I/O on an HP-IB/GPIO/parallel channel io_burst(3l) 

perform setup required for stream data conversion ASetupConversion(3X) 

perform special operations on NetlPC sockets ipccontrol(2) 

perform word expansions .wordexp(3C) 

permissions mask for file creation, set and get umask(2) 

permissions (mode) of file, change access '. chmod(2) 
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per-process timer, allocate a jnktimer(3C) 

per-process timer, free a rmtimer(3C) 

per-process timer, get value of a gettimer(3C) 

per-process timer, relatively arm a jceltimer(3C) 

perrorO, errno(), sys_errlist ( ) , sys_nerr() - system error messages perror(3C) 

pfm_$bad_rls_order .pfm_$intro(3) 

pfm_$cleanup() -establish a cleanup handler pfm_$cleanup(3) 

pfm_$cleanup_not_foiind .pfm_$intro(3) 

pfm_$cleanup_rec pfm_$intro(3) 

pfm_$cleanup_set pfm_$intro(3) 

pfm_$cleanup_set_signalled .pfm_$intro(3) 

pf m_$enable ( ) - enable asynchronous faults pfm_$enable(3) 

pfm_$enable_f aults ( ) - enable asynchronous faults pfm_$enable_faults(3) 

pfm.h pfm_$intro(3) 

pfm_$inliibit_f aults ( ) - inhibit asynchronous faults; allow time-sliced task switcbiBBfm_$inhibit_faults(3) 

pf m_$inliibit ( ) - inhibit asynchronous faults pfm_$inbibit(3) 

pf m_inhibit ( ) -pointer entry for conflicting online manual entries pfm_inhibit(3) 

pfm_$init ( ) - initialize the process fault manager package pfm_$init(3) 

p£m_$init_signal_handlers .pfm_$intro(3) 

pfm_$intro - fault management .pfm_$intro(3) 

pfm_$invalid_cleanup_rec .pfm_$intro(3) 

pfm_$no_space pfm_$intro(3) 

PFM package, initiahze the pfm_$init(3) 

pf m_$reset_cleanup ( ) -reset a cleanup handler pfm_$reset_cleanup(3) 

pf m_$rls_cleanup ( ) - release a cleanup handler pfm_$rls_cleanup(3) 

pfm_$signal() - signal the calling process pfm_$signal(3) 

pgm_$exit ( ) - exit a program .pgm_$exit(3) 

pgm_$intro - program management .pgm_$intro(3) 

pipe ( ) - create an interprocess channel pipe(2) 

pipe I/O to or from a process, open or close popen(3S) 

play attributes to use when creating a new file, select AChoosePlayAttributes(3X) 

play operation, initiate an audio widget AuInvokePlay(3X) 

play specified sound bucket and return transaction ID APlaySBucket(3X) 

play widget, audio AuPlayWidget(3X) 

play widget, create an audio AuCreatePlay(3X) 

plock() - lock process, text, or data in memory plock(2) 

pmap_getmaps () - get listofRPC program-to-port mappings rpc(3C) 

pmap_getport ( ) - get port number on which waits supporting service rpc(3C) 

pmap_rmtcall ( ) - instruct portmapper to make an RPC call rpc(3C) 

pmap_set () - set [prognum,versnum,procnum]-to-port mapping rpc(3C) 

pmap_unset ( ) - destroy [prognum,versnum,procnum]-to-port mapping rpc(3C) 

pointer array, sort a directory scandir(3C) 

pointer entry for conflicting online manual entries pfm_inbibit(3) 

pointer, file, move read/write lseek(2) 

pointer for binary search tree, get data tsearch(3C) 

pointer for I/O operations on a stream file, get or reposition fseek(3S) 

pointer, stream, map to file descriptor £leno(3S) 

pointer to login name inutmpO, get getlogin(3C) 

poll - monitor I/O conditions on multiple file descriptors poll(2) 

poll on HP-IB bus, conduct a serial Jipib_spoll(3l) 

poll on HP-IB bus, conduct parallel Japib_ppoll(3l) 

poll on HP-IB, control response to parallel hpib_cardjppoll_resp(3l) 

poll, parallel, define interface response hpib_ppoll_resp_ctl(3l) 

poll value occurs, wait until a particular parallel hpib_wait_on_ppoll(3l) 

popen( ) - initiate pipe I/O to or from a process popen(3S) 

portable pfm_$ interface pfm_$intro(3) 

port, IP, bind socket to a privileged bindresvport(3N) 

port number, RPC, get getrpcport(3N) 
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power, logarithm, exponential, square root, cube root functions exp(3M^ 

powf (), pow() - power function .exp(3M' 

pow( ) , powf ( ) - power function .exp(3Mi 

preallocate fast disk storage prealloc(2 

prealloc() -preallocate fast disk storage ..,.„„„„„.„„„........, prealloc(2) 

prepare execution profile jnonitor(3C 

presence of hardware capabilities, check for is_hw_jpresent(3C 

preset contents of memory area to specified character memory(3C 

printf ( ) , al_printf ( ) - print formatted output to standard output printf(3S 

print formatted output of a varargs argument list vprintf(3S 

print formatted output to standard output, file, or string ,...,..,.„„.„,,„„,„,,,, .„..„. = .,.„,.„,„„... ..„,print£(83^ 

print formatted output with numbered arguments to a file or string printmsg(3C 

printmsg ( ) - print formatted output with numbered arguments to standard output printmsg(3C 

priority, get process getpriority(2' 

priority of a process, change Jiice(2 

priority, set process setpriority© 

privileged IP port, bind socket to a bindresvport(3N) 

procedure calls, remote, library routines for xpc(3C 

process 16-bit characters, tools to nl_tools_16(3Q 

process accounting, enable or disable .acct(2 

process and child process times, get times (2 

process, calling, set or clear auditing on setaudproc(2 

process, change priority of a nice(2i 

process context for context-dependent file search, return getcontext® 

process, create anew fork(2 

process environment, clear the clearenv(3C 

process' expected paging behavior, advise system of madvise(2 

process fault management pfm_$intro(3^ 

process fault manager package, initialize the pfm_$init(3' 

process, get audit ID (aid ( ) ) for current getaudid(2 

process, get audit process flag for calling getaudproc(2^ 

process group ID, create session and set setsid(2| 

process group ID, foreground, get tcgetpgrp(3C 

process group ID, foreground, set .tcsetpgrp(3C 

process group ID for job control, set .setpgid(2 

process interval timer, set or get value of getitimer(2 

process, lock into memory after allocating data and stack space datalock(3C 

process, open or close pipe I/O to or from a .popen(3S 

process or a group of processes, send a signal to a kill(2 

processor type, determine -sysconf(2 

process priority, get getpriority(2 

process priority, set setpriority(2 

process, process group, or parent process ID, get getpid(2 

process, request connection to another ipcconnect(2 

process's alarm clock, set alarm (2 

process, self-auditing, write audit record for audwrite(2 

process, set audit ID (aid ()) for current setaudid(2 

process, signal the calling .pfm_$signal(3 

process, spawn new (use fork ( ) instead) vfork(2 

process, suspend or resume auditing on current audswitch(2 

process, suspend until signal pause (2 

process, terminate exit (2 

process, text, or data, lock in memory .plock(2 

process to stop or terminate, wait for child or traced wait(2 

process trace p trace (2 

profile, execution time profil(2 

profile of execution, prepare jnonitor(3C 

prof il ( ) - execution time profile profil(2 
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program assertion, verify assert (3X) 

program, exit a pgm_$exit(3) 

program, get or set the locale of a setlocale(3C) 

program, initialize the NLS environment of a nl_init(3C) 

program management pgm_$intro(3) 

program message, get an NLS .catgets(3C) 

program regions, first locations beyond allocated end(3C) 

program termination, register a function to be called at atexit(2) 

protections, modify memory mapping access mprotect(2) 

protocol entry, get or set .getprotoent(3N) 

provide semaphores and record locking on files lockf(2) 

provide text describing NetlPC error number ipcerrmsg(3N) 

pseudo-random numbers, generate uniformly distributed drand48(3C) 

ptrace ( } - process trace ptrace(2) 

ptsname - get the name of a slave pty ptsname(3C) 

pty, get the name of a slave ptsname(3C) 

purge and/or flush the cache .cachectl(3C) 

push character back into input stream ungetc(3S) 

push event onto head of audio event queue APutBackEvent(3X) 

push wide character back into input stream ungetwc(3C) 

put a string on a stream puts(3S) 

putc ( ) , fputc ( ) - put character on a stream putc(3S) 

put character or word on a stream putc(3S) 

putchar ( ) - put character on stream standard output putc(3S) 

putenv( ) - change or add value to environment putenv(3C) 

putpwent ( ) - write password file entry putpwent(3C) 

putspwent () - write secure password file entry putspwent(3C) 

puts ( ) - write null-terminated string to stream stdout ( ) puts(3S) 

_pututline ( ) - update or create entry in a utmp ( ) file getut(3C) 

pututline ( ) - update or create entry in a utmp( ) file getut(3C) 

putwc ( ) , fputwc ( ) - put wide character on a stream putwc(3C) 

putwchar() -put wide character on stream standard output putwc(3C) 

put wide character on a stream putwc(3C) 

put word or character on a stream putc(3S) 

putw( ) - put word (integer) on a stream putc(3S) 

qsort ( ) - quicker sort .qsort(3C) 

query numeric formatting conventions of current locale localeconv(3C) 

quicker sort qsort(3C) 

quotactl ( ) - manipulate disk quotas quotactl(2) 

quotas, manipulate disk .quotactl(2) 

raise a software signal ssignal(3C) 

raise ( ) - raise a software signal Jdll(2) 

rand() -generate successive random numbers rand(3C) 

random-number generator, simple jeand(3C) 

rate of I/O data transfer, inform system of required minimum io_speed_ctl(3l) 

rcmd( ) : return a stream to a remote command rcmd(3N) 

read audio data into sound bucket _ARecordAData(3X) 

readdir ( ) - get pointer to current entry in open directory directory(3C) 

read from stream file or character string with formatted input conversion scanf(3S) 

reading or writing, open file for .open(2) 

read, I/O, determine how last terminated io_get_term_reason(3l) 

readlinkO -read value of a symbolic link readlink(2) 

readopt ( ) - obtain option code and data fromNetlPC option buffer readopt(3N) 

read or change real-time priority rtprio(2) 

read password from terminal while suppressing echo getpass(3C) 

read( ) - read contiguous data from a file .read(2) 

read termination character on special file, set up I/O io_eol_ctl(3I) 

read value of a symbolic link readlink(2) 
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readv() - read non-contiguous data from a file read(2) 

read/write file pointer, move lseek(2) 

real, effective, and/or saved user or group IDs, set setresuid(2) 

reallocO -change size of allocated memory block malloc(3C) 

real or effective user or group ID, get getuid(2) 

reboot ( ) - boot the system reboot (2) 

receipt of a signal, define what to do upon signal(2) 

receive connection request on a call socket ipcrecvcn(2) 

receive dataonNetlPC virtual circuit connection ipcrecv(2) 

receive message from a socket recv(2) 

receive message from message queue ,,,,,,,. msgop(2) 

record, audit, write for self-auditing process audwrite(2) 

record locking and semaphores on files, provide lockf(2) 

record operation, initiate an audio widget AuInvokeRecord(3X) 

record widget, audio AuRecordWidget(3X) 

record widget, create an audio AuCreateRecord(3X) 

record widget, save sound bucket data created by AuSaveFile(3X) 

recursively descend a directory hierarchy itw(3C) 

recvf rom( ) - receive message from a socket recv(2) 

recvmsg ( ) - receive message from a socket .recv(2) 

rscv() - receive message from a socket xecv(2) 

regcmp ( ) - compile a regular expression jregcmp(3X) 

regcomp ( ) - regular expression matching routines regcomp(3C) 

regerrorO - regular expression matching routines regcomp(3C) 

regexecO - regular expression matching routines regcomp(3C) 

regex ( ) - execute a regular expression against a string regcmp(3X) 

regf ree ( ) - regular expression matching routines regcomp(3C) 

region, initialize semaphore in mapped file or anonymous memory msem_init(2) 

region, remove semaphore in mapped file or anonymous msem_remove(2) 

regions, first locations beyond allocated program end(3C) 

region, unmap a mapped jnunmap(2) 

register a function to be called at program termination atexit(2) 

registerrpc ( ) - register procedure with RPC service package rpc(3C) 

regular expression compile and match routines regexp(3X) 

regular expression, compile or execute against a string regcmp(3X) 

regular expression matching routines j*egcomp(3C) 

relatively arm a per-process timer reltimer(3C) 

release a cleanup handler .pfm_$rls_cleanup(3) 

release a descriptor ipcshutdown(2) 

release blocked signals and atomically wait for interrupt sigpause(2) 

release server from exclusive use by this connection AUngrabServer(3X) 

reltimer - relatively arm a per-process timer reltimer(3C) 

remainder, ceiling, floor, absolute value, round-to-nearest functions floor(3M) 

remainder, integer division and div(3C) 

remainder manipulations ieee(3M) 

remexportent ( ) - access exported file system information exportent(3N) 

remote command, return a stream to xcmd(3N) 

remote command, return stream to a rexec(3N) 

Remote Enable line on HP-IB, control the lipib_ren_ctl(3l) 

remote kernel, get performance data from rstat(3N) 

remotely mounted file systems, keep track of mount(3N) 

remote machines, return information about users on rnusers(3N) 

remote machines, write to specified xwall(3N) 

remote node, get file handle for file on getfh(2) 

remote procedure calls, library routines for .rpc(3C) 

remove a directory file rmdir(2) 

remove directory entry; delete file or directory name unlink(2) 

remove ( ) - remove a file remove(3C) 
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remove semaphore in mapped file or anonymous region msem_remove(2) 

rename ( ) - change the name of a file jpenaine(2) 

re-open or open a stream file; convert file to stream fopen(3S) 

replace default error handler with specified handler ASetErrorHandler(3X) 

replace default I/O error handler with specified handler ASetIOErrorHandler(3X) 

report CPU time used jclock(3C) 

reposition or get pointer for I/O operations on a stream file fseek(3S) 

representation, library routines for external data xdr(3C) 

request connection to another process ipcconnect(2) 

requested status condition becomes true, wait until the hpib_status_wait(3I) 

request on a call socket, receive connection ipcrecvcn(2) 

request report of specified audio events ASelectInput(3X) 

required minimum I/O data transfer rate, inform system of io_speed_ctl(3l) 

reset a cleanup handler .pfm_$reset_cleanup(3) 

reset an I/O interface io_reset(3l) 

res_init ( ) - resolver routines xesolver(3N) 

res_mkquery() - resolver routines xesolver(3N) 

resolver routines resolver(3N) 

resource consumption limit, get or set system getrlimit(2) 

response, define interface parallel poll hpib_ppoll_resp_ctl(3l) 

response to parallel poll on HP-IB, control hpib_cardjDpoll_resp(3l) 

res_query ( ) - resolver routines jcesolver(3N) 

res_search( ) - resolver routines jresolver(3N) 

res_send ( ) - resolver routines resolver(3N) 

restore or save file position indicator for a stream fgetpos(3S) 

restore/save stack environment for non-local goto setjmp(3C) 

restore signal action sigset(2V) 

resume or suspend auditing on current process audswitch(2) 

resume specified audio transaction AResumeAudio(3X) 

resvport (): return a stream to a remote command rcmd(3N) 

return a stream to a remote command xcmd(3N) 

return but do not dequeue first event in audio event queue APeekEvent(3X) 

return character back into input stream ungetc(3S) 

return gain matrix of basic play device ASimplePlayer(3X) 

return gain matrix of basic recording device ASimpleRecorder(3X) 

return information about users on remote machines rnusers(3N) 

return integer absolute value abs(3C) 

return list of sampling rates supported by audio controller ASamplingRates(3X) 

return number of bytes needed by a NetlPC option optoverhead(3N) 

return number of data formats supported by audio controller ANumDataFormats(3X) 

return number of events on audio event queue AQLength(3X) 

return number of sampling rates supported by audio controller ANumSamplingRates(3X) 

return process context for context-dependent file search getcontext(2) 

return status of HP-IB interface hpib_bus_status(3l) 

return stream to a remote command jcexec(3N) 

return the size in bytes of converted data ACalculateLength(3X) 

return wide character back into input stream ungetwc(3C) 

rewinddir ( ) - reset position of named directory stream to beginning of directory directory(3C) 

rewind legal user shells file getusershell(3C) 

rewind () -set position of next I/O operation on stream file fseek(3S) 

rewrite an existing file jcreat(2) 

rexec ( ) : return stream to a remote command rexec(3N) 

rights to a file, get a user's effective access getaccess(2) 

right triangle, hypotenuse of a .hypot(3M) 

rindexO - BSD portability string routine string(3C) 

rint ( ) , f absf ( ) , f abs ( ) , floor ( ) , ceil ( ) , 

fmod( ) , fmodf ( ) - round-to-nearest, absolute value, floor, ceiling, remainder functions floor(3M) 

rmdir ( ) - remove a directory file .rmdir(2) 
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rmtimer - free a per-process timer jrmtimer(3C) 

rnusers ( ) : return information about users on remote machines rnusers(3N) 

root directory, change jchroot(2) 

rounding mode (floating-point), examine and set fpgetround(3M) 

round-to-nearest, absolute value, floor, ceiling, remainder functions fioor(3M) 

routine for sorted tables, binary search bsearch(3C) 

routines, CRT screen handling and optimization curses(3X) 

routines, emulate /etc/termcap access termcap(3X) 

routines for external data representation, library xdr(3C) 

routines, Internet address manipulation inet(3N) 

routines, network station address string conversion net_aton(3C) 

routines, resolver resolver(3N) 

rpc ( ) : library routines for remote procedure calls rpc(3C) 

rpc_createerr() - global variable reason why client creation failed rpc(3C) 

RPC entry, get getrpcent(3C) 

RPC port number, get getrpcport(3N) 

rstat () -get performance data from remote kernel rstat(3N) 

RTE/MPE-style message catalog support catread(3C) 

rtprio ( ) - change or read real-time priority jptprio(2) 

ruserokO : return a stream to a remote command rcmd(3N) 

misers ( ) : return information about users on remote machines rnusers(3N) 

rwall ( ) : write to specified remote machines rwall(3N) 

saved, real, and/or effective user or group IDs, set setresuid(2) 

save or restore file position indicator for a stream fgetpos(3S) 

save/restore stack environment for non-local goto setjmp(3C) 

save sound bucket data created by record widget AuSaveFile(3X) 

sbrk() - increase data segment space allocation brk(2) 

scalb ( ) , logb ( ) - exponent manipulations ieee(3M) 

scan a directory scandir(3C) 

scandir ( ) - scan a directory .scandir(3C) 

scanf ( ) , nl_scanf ( ) - formatted read from standard input stream file scanf(3S) 

scatter data to check the network .spray(3N) 

screen handling and optimization package, CRT curses(3X) 

search, context-dependent file, return process context for getcontext(2) 

search environment list for value of specified variable name getenv(3C) 

search routine, binary, for sorted tables bsearch(3C) 

search table for entry; optional update if missing lsearch(3C) 

search tables, hash, manage Jjsearch(3C) 

search tree, manage a binary .tsearch(3C) 

secof2 (), SECof2() - test for valid second byte in 16-bit character nl_tools_16(3C) 

secure password file entry, write putspwent(3C) 

secure password file, get entry from getspwent(3C) 

seekdir ( ) - set position of next readdir ( ) operation on named directory stream directory(3C) 

seek; move read/write file pointer lseek(2) 

segment, get shared memory shmget(2) 

select attributes to use when creating a new file AChooseAFileAttributes(3X) 

select attributes to use when creating a new file AChoosePlayAttributes(3X) 

select attributes to use with an existing file or a stream AChooseSourceAttributes(3X) 

select ( ) - synchronous I/O multiplexing select(2) 

self-auditing process, write audit record for audwrite(2) 

semaphore control operations semctl(2) 

semaphore in mapped file or anonymous memory region, initialize msem_init(2) 

semaphore in mapped file or anonymous region, remove msem_remove(2) 

semaphore, lock a .....msem_lock(2) 

semaphore operations semop(2) 

semaphores and record locking on files, provide lockf(2) 

semaphores, get set of semget(2) 

semaphore, unlock a jnsem_unlock(2) 
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semctl ( ) - semaphore control operations semctl(2) 

semget () -get set of semaphores .semget(2) 

semop ( ) - semaphore operations semop(2) 

send a signal to a process or a group of processes kill (2) 

send command bytes over HP-IB Jipib_send_cmnd(3l) 

send data on a virtual circuit connection ipcsend(2) 

send message to a socket send(2) 

send message to message queue jnsgop(2) 

sendmsg ( ) - send message to a socket send(2) 

send( ) - send message to a socket .send(2) 

sendto ( ) - send message to a socket .send(2) 

separate floating-point into mantissa and exponent frexp(3C) 

serial poll on HP-IB bus, conduct a Jipib_spoll(3l) 

service entry, get or set getservent(3N) 

session, create and set process group ID setsid(2) 

set: file creation (permissions) mask, set and get umask(2) 

set: file size limits and break value, get or set ulimit(2) 

set: process priority setpriority(2) 

set: system clock date and time gettimeofday(2) 

set access control list (ACL) information setacl(2) 

setaclentryO - add, modify, or delete access control list entry setaclentry(3C) 

setacl ( ) , f setacl ( ) - set access control list (ACL) information setacl(2) 

set and/or get signal stack context jsigstack(2) 

set a process's alarm clock alarm(2) 

setaudidO - set audit ID (aid ()) for current process setaudid(2) 

set audit ID (aid ()) for current process setaudid(2) 

setaudproc ( ) - set or clear auditing on calling process setaudproc(2) 

setbuf ( ) , setvbuf ( ) - assign buffering to a stream file setbuf(3S) 

set callback to NULL AtRemoveCallback(3X) 

setccent ( ) - rewind cluster configuration pointer to beginning of file getccent(3C) 

setclock- set value of system-wide clock setclock(3C) 

set close-down mode on specified connection ASetCloseDownMode(3X) 

set contents of memory area to specified character memory(3C) 

set current ignorable signals mask sigsetmask(2) 

setdomainname ( ) - set name of current NIS domain getdomainname(2) 

set event ( ) - set current events and system calls to be audited setevent(2) 

setexportent ( ) - access exported file system information exportent(3N) 

set foreground process group ID .tcsetpgrp(3C) 

setf sent ( ) - open and rewind file system descriptor file getfsent(3X) 

setgidO - set group ID jsetuid(2) 

setgrent ( ) - rewind pointer to first entry in group ( ) file getgrent(3C) 

set group access fist setgroups(2) 

setgroups ( ) - set group access list setgroups(2) 

sethostent () -get network host entry gethostent(3N) 

sethostname ( ) - set name of host cpu seth.ostname(2) 

setitimer() - set value of process interval timer getitimer(2) 

_setjmp() - save stack environment for non-local goto setjmp(3C) 

setkeyO -generate hashing encryption crypt(3C) 

setlocale ( ) - set the locale of a program setlocale(3C) 

setlogmaskO - set system log file priority mask syslog(3C) 

setmntent ( ) - open a file system description file getmntent(3X) 

set name of current NIS domain getdomainname(2) 

set name of host cpu sethostname (2) 

setnetent ( ) : get network entry getnetent(3N) 

setnetgrent ( ) - get network group entry getnetgrent(3C) 

set NetlPC node name of host CPU ipcsetnodename(2) 

set network entry getnetent(3N) 

set network group entry .getnetgrent(3C) 
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set network host entry gethostent(3N) 

set of semaphores, get semget(2) 

set or clear auditing on calling process setaudproc(2) 

set or get audit files audctl(2) 

set/ or ge»/ wy usiiu rate .cispsca^^} 

set or update file access and modification times utime(2) 

setpgid ( ) , - set process group ID for job control setpgid(2) 

setpgrp2 ( ) : set process group ID .setpgid(2) 

setpgrp ( ) - create session and set process group ID setsid(2) 

set play volume or record gain of specified transaction ASetGain(3X) 

setpriority — set process priority setpnontyvAi 

set process group ID, create session and setsid(2) 

set process group ID for job control .setpgid(2) 

set protocol entry getprotoent(3N) 

setprotoent ( ) : -get protocol entry getprotoent(3N) 

setpwent ( ) - rewind pointer to beginning of password file getpwent(3C) 

set real, effective, and/or saved user or group IDs setresuid(2) 

setresgidO - set real, effective, and/or saved group IDs setresuid(2) 

setresuidO - set real, effective, and/or saved user IDs setresuid(2) 

setrlimit () - get system resource consumption limit getrlimit(2) 

set servant () : get service entry getservent(3N) 

setsidO, setpgrp () -create session and set process group ID setsid(2) 

setsockopt () - set options on sockets getsockopt(2) 

setspwent () - rewind pointer to beginning of secure password file getspwent(3C) 

set system or monitor audio channel gain ASetSystemChannelGain(3X) 

set system play volume ASetSystemPlayGain(3X) 

set system record gain ASetSystemRecordGain(3X) 

set system resource consumption limit .getrlimit(2) 

set the locale of a program jsetlocale(3C) 

set time and date stime(2) 

set time limit for I/O operations io_timeout_ctl(3l) 

settimeofdayO - set system clock date and time gettimeofday(2) 

set transaction channel gain ASetChannelGain(3X) 

set tty device operating parameters tcattribute(3C) 

setuid() -set user ID jsetuid(2) 

set up I/O read termination character on special file io_eol_ctl(3l) 

set user or group ID setuid(2) 

setusershell ( ) - rewind legal user shells file getusershell(3C) 

setutent ( ) - reset input stream to beginning of utmp ( ) file getut(3C) 

set value of process interval timer .getitimer(2) 

set value of system- wide clock jsetclock(3C) 

set width (in bits) of datapath io_width_ctl(3l) 

sgetl ( ) - retrieve a 4-byte long integer from memory sputl(3X) 

shared library, load or unload shl_load(3X) 

shared library, look up symbol in shl_load(3X) 

shared memory and data segment, attach or detach shmop(2) 

shared memory control operations .shmctl(2) 

shared memory segment, get jshmget(2) 

shell command, issue a system(3S) 

shells, get legal user getusershell(3C) 

shl_f indsym( ) - look up symbol in shared library shl_load(3X) 

shl_get ( ) - get information about shared library shl_load(3X) 

shl_load( ) - load shared library shl_load(3X) 

shl_unload() -unload shared library shl_load(3X) 

shmat ( ) - attach shared memory to data segment shmop(2) 

shmctl ( ) - shared memory control operations shmctl(2) 

shmdt ( ) - detach shared memory from data segment shmop(2) 

shmget ( ) - get shared memory segment shmget(2) 
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shut down a socket shut down (2) 

shutdown ( ) - shut down a socket shut down (2) 

sigactionO - examine and change signal action sigaction(2) 

sigaddset ( ) - initialize, manipulate, and test signal sets sigsetops(3C) 

sigblock ( ) - block signals sigblock(2) 

sigdelset ( ) - initialize, manipulate, and test signal sets sigsetops(3C) 

sigemptyset ( ) - initialize, manipulate, and test signal sets sigsetops(3C) 

sigf illset () - initialize, manipulate, and test signal sets sigsetops(3C) 

sighold( ) , sigrelse ( ) , sigignore ( ) , sigpause ( ) , sigset ( ) - signal management sigset(2V) 

sigignore ( ) , sigpause ( ) , sigset ( ) , sighold( ) , sigrelse ( ) - signal management sigset(2V) 

sigismember () - initialize, manipulate, and test signal sets sigsetops(3C) 

signal () -4.2 BSD-compatible signal () system call bsdproc(2) 

signal action, examine and change sigaction(2) 

signal, define what to do upon receipt of a signal (2) 

signal exceptions, managing pfm_$intro(3) 

signal facilities, software sigvector(2) 

signal, hold upon receipt sigset(2V) 

signal, ignore sigset(2V) 

signal management (sigset (), sigholdO, sigrelse (), sigignore(), sigpause ()) sigset(2V) 

signal, raise a software kill(2) 

signal, raise a software ssignal(3C) 

signal, restore action sigset(2V) 

signals, blocked, examine and change sigprocmask(2) 

signals, block sigblock(2) 

signal, select method of handling .sigset(2V) 

signal, send to a process or a group of processes kill(2) 

signal sets, initialize, manipulate, and test sigsetops(3C) 

signals, examine pending sigpending(2) 

signals mask, set current ignorable sigsetmask(2) 

signal () - specify what to do upon receipt of a signal signal(2) 

signals, release blocked and atomically wait for interrupt sigpause (2) 

signal stack context, set and/or get sigstack(2) 

signal stack space, define, delete, or get amount of sigspace(2) 

signal, suspend calling process until received sigset(2V) 

signal, suspend process until .pause(2) 

signal ( ) system call, 4.2 BSD -compatible bsdproc(2) 

signal the calling process pfm_$signal(3) 

signal, wait for a sigsuspend(2) 

signgam( ) , gamma ( ) , lgamma ( ) - log gamma function gamma(3M) 

sigpause ( ) - atomically release blocked signals and wait for interrupt sigpause(2) 

sigpause ( ) , sigset ( ) , sigholdO , sigrelse ( ) , sigignore ( ) - signal management sigset(2V) 

sigpending ( ) - examine pending signals sigpending(2) 

sigprocmask ( ) - examine and change blocked signals sigprocmask(2) 

sigrelse(), sigignore (), sigpause (), sigset (), sigholdO - signal management sigset(2V) 

sigsetmask ( ) - set current ignorable signals mask sigsetmask(2) 

sigset (), sigholdO, sigrelse (), sigignore (), sigpause () - signal management sigset(2V) 

sigspace ( ) - define or delete additional signal stack space sigspace(2) 

sigstackO - set and/or get signal stack context sigstack(2) 

sigsuspendO - wait for a signal sigsuspend(2) 

sigvec ( ) - 4.2 BSD-compatible sigvec ( ) system call bsdproc(2) 

sigvec ( ) system call, 4.2 BSD -compatible bsdproc(2) 

sigvectorO - software signal facilities sigvector(2) 

sindf ( ) - trigonometric sine function (float, degrees) trigd(3M) 

sind() - trigonometric sine function (degrees) trigd(3M) 

sine trigonometric function (degrees) .trigd(3M) 

sine trigonometric function .trig(3M) 

sinf ( ) - trigonometric sine function (float) trig(3M) 

sinhf ( ) , sinh ( ) - hyperbolic sine functions sinh(3M) 
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sinh(), sinhf () -hyperbolic sine functions sinh(3M) 

sin() - trigonometric sine function .trig(3M) 

sixteen-bit characters, tools to process nl_tools_16(3C) 

slave pty, get the name of a .ptsname(3C) 

a]_aan i \ — sus r, end execution for interval s1ssij(3C) 

slot in the utmp ( ) file of the current user, find ttyslot(3C) 

socket, accept connection on a .accept(2) 

socket address, get getsockname(2) 

socket, bind address to a bind(2) 

socket, bind to a privileged IP port bindresvport(3N) 

socket ( ) - create an end n oint for communication sockst(2) 

socket, initiate connection on a .connect(2) 

socket, listen for connections on a listen(2) 

socket or destination call socket, associate name with call ipcname(2) 

socket or destination call socket, delete name associated with a call ipcnamerase(2) 

socket or VC socket, determine status of call ipcselect(2) 

socketpairO - create a pair of connected sockets socketpair(2) 

socket, receive connection request on a call ipcrecvcn(2) 

socket, receive message from a recv(2) 

sockets, create a pair of connected .socketpair(2) 

socket, send message to a send(2) 

sockets, get or set options on .getsockopt(2) 

socket, shut down a shutdown(2) 

sockets, perform special operations on NetlPC ipccontrol(2) 

software signal facilities jsigvector(2) 

software signal, raise a kill (2) 

software signal, raise a ssignal(3C) 

sort a directory pointer array scandir(3C) 

sorted tables, binary search routine for bsearch(3C) 

sort, quicker jqsort(3C) 

sound bucket data created by record widget, save AuSaveFile(3X) 

space allocation, change data segment ...brk(2) 

space for signal stack, define, delete, or get amount of sigspace(2) 

space, stack and data, allocate then lock process into memory datalock(3C) 

spawn new process (use fork ( ) instead) vfork(2) 

special file, control character device ioctl(2) 

special file, FIFO, make a jnkfifo(3C) 

special file, set up I/O read termination character on io_eol_ctl(3l) 

special operations onNetlPC sockets, perform ipccontrol(2) 

special or ordinary file, make a directory, or a mknod(2) 

specified file, get file attributes of AGetAPileAttributes(3X) 

specified remote machines, write to jrwall(3N) 

specify I/O read termination character on special file io_eol_ctl(3l) 

specify what to do upon receipt of a signal signal(2) 

speed, inform system of required minimum I/O transfer io_speed_ctl(3l) 

split floating-point into mantissa and exponent frexp(3C) 

spray: scatter data to check the network spray(3N) 

sprintf ( ) , nl_sprintf ( ) - print formatted output to a string printf(3S) 

sprintmsg ( ) - print formatted output with numbered arguments to a string printmsg(3C) 

sputl ( ) - place a 4-byte long integer in memory sputl(3X) 

sqrt(), cbrt(), sqrtf ( ), cbrtf () - square root, cube root functions exp(3M) 

sqrtf (), sqrt (), cbrt (), cbrtf () - square root, cube root functions exp(3M) 

square root, power, logarithm, exponential, cube root functions exp(3M) 

srand48 ( ) , seed48 ( ) , lcong48 ( ) - initialize pseudo-random number generator drand48(3C) 

srand() - reset random-number generator to random starting point rand(3C) 

SRQ line on HP-IB, allow interface to enable hpib_rqst_srvce(3l) 

sscanf ( ) , nl_sscanf ( ) - formatted read from character string scanf(3S) 

s signal ( ) - raise a software signal and perform an action ssignal(3C) 
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stack and data space, allocate then lock process into memory datalock(3C 

stack context, signal, set and/or get sigstack(2 

stack environment, save/restore for non-local goto setjmp(3C 

stack space for signals, define, delete, or get amount of sigspace(2 

standard buffered input/output stream file package stdio(3S^ 

standard input stream, input string from a gets(3S 

standard input stream, input wide string from a getws(3C 

standard interprocess communication package stdipc(3C) 

start or halt auditing system audctl(2 

state with its state on disk, synchronize a file's in-core fsync(2 

statfsdev(), f statf sdev( ) -get file system statistics statfsdev(3C 

statf s ( ) , f statf s ( ) - get file system statistics statfs(2 

station address string conversion routines, network net_aton(3C 

statistics, get file system statfs(2i 

statistics, get file system jstatfsdev(3C 

statistics, get mounted file system .ustat(2 

stat ( ) , lstat ( ) , f stat ( ) - get file status stat(2 

status code, return an error message for a error_$c_text(3 

status code, return subsystem, module, and error texts for a error_$c_get_text(3 

status condition becomes true, wait until the requested hpib_status_wait(3l) 

status, get file stat(2 

status inquiries, stream ferror(3& 

status lines of GPIO card, return gpio_get_status(3l 

status of call socket or VC socket, determine ipcselect(2 

status of HP-IB interface, return bpib_bus_status(3r 

std_$call pfm_$intro(3 

stdioO - standard buffered input/output stream file package stdio(3S 

step ( ) - regular expression string comparison routine regexp(3X' 

s time ( ) - set time and date jstime(2 

stop activity on specified HP-IB Jipib_abort(3l 

stop or terminate, wait for child or traced process to wait(2 

stop specified audio transaction AStopAudio(3X 

storage, preallocate fast disk prealloc(2" 

store ( ) - store data under a key (old single-data-base version) dbm(3X, 

strcat ( ) , strncat ( ) - append string 2 to string 1 string(3C 

strchr ( ) , strrchr ( ) - get pointer to character in string string(3C 

strcmpl6 ( ) , strncmpl6 ( ) -non-ASCII 16-bit character string collation nl_string(3C 

strcmp8 ( ) , strncmp8 ( ) - non-ASCII 8-bit character string collation nl_string(3C 

strcmpO, strncmpO -compare two strings string(3C 

strcoll ( ) - process string of text tokens string(3C 

strcpyO, strncpyO - copy string 2 to string 1 string(3C 

strcspnO, strspnO -find length of matching substrings string(3C 

stream, close a fclose(3S 

stream file, assign buffering to a .setbuf(3S' 

stream file, buffered binary input/output to a fread(3S 

stream file, get character or data word from a getc(3S 

stream file, get or reposition pointer for I/O operations on a fseek(3S^ 

stream file, get wide character from a getwc(3C 

stream file, open or re-open; convert file to stream fopen(3S^ 

stream file or character string, read from with formatted input conversion scanf(3§ 

stream file package, standard buffered input/output stdio(3S' 

stream, flush buffer with or without closing fclose(3S 

stream, input string from a standard input gets(3S' 

stream, input wide string from a standard input getws(3C 

stream pointer, map to file descriptor £leno(3S' 

stream, push character back into input ungetc(3S 

stream, push wide character back into input ungetwc(3C' 

stream, put wide character on a .putwc(3C' 
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stream, put word or character on a .putc(3S) 

stream, return to a remote command xcmd(3N) 

stream, return to a remote command .rexec(3N) 

stream, save or restore file position indicator for a fgetpos(3S) 

stream status inquiries ferror(3S) 

strerror ( ) - system error messages .perror(3C) 

strftime() - convert date and time to string strftime(3C) 

string collation, non-ASCII Jil_string(3C) 

string conversion routines, network station address net_aton(3C) 

string, convert between long integer and base-64 ASCII a64l(3C) 

string, convert date and time to ctime(3C) 

string, convert date and time to .strftime(3C) 

string, convert date and time to wide-character wcsftime(3C) 

string, convert long double floating-point number to ldcvt(3C) 

string, convert long integer to ltostr(3C) 

string, convert to access control list (ACL) structure strtoacl(3C) 

string, convert to floating-point number cvtnum(3C) 

string, convert to long double-precision number strtold(3C) 

string data order, convert strord(3C) 

string form, convert access control list (ACL) structure to acltostr(3C) 

string from a standard input stream, input gets(3S) 

string operations, character string(3C) 

string operations, wide character .wcstring(3C) 

string or string array element, convert floating-point number to ecvt(3C) 

string, parse suboptions from a getsubopt(3C) 

strings and characters conversions, multibyte multibyte(3C) 

strings, concatenate two string(3C) 

string to double-precision number, convert strtod(3C) 

string to long integer, convert .strtol(3C) 

string-valued configuration values, get confstr(3C) 

strlenO - determine length of a string string(3C) 

strord ( ) - convert string data order strord(3C) 

strpbrk() - find occurrence of character from string 2 in string 1 string(3C) 

strrstrO -process string of text tokens string(3C) 

strspn( ) , strcspn( ) - find length of matching substrings string(3C) 

strstr ( ) - process string of text tokens string(3C) 

strtoacl ( ) - convert exact string form to access control list (ACL) structure strtoacl(3C) 

strtoaclpatt ( ) - convert pattern string form to access control list (ACL) structure strtoacl(3C) 

strtodO - convert string to double-precision number strtod(3C) 

strtok ( ) - process string of text tokens string(3C) 

strtol ( ) - convert string to long integer strtol(3C) 

strtoldO -convert string to long double-precision number strtold(3C) 

strxf rm( ) - process string of text tokens string(3C) 

stty(), gtty() - control terminal device (Version 6 compatibility only) stty(2) 

suboptions, parse from a string getsubopt(3C) 

subroutines and libraries, introduction to intro(3) 

subroutines, database (new multiple database version) ndbm(3X) 

subroutines, database (old version - see also ndbm(3X)) dbm(3X) 

subsystem, module, and error texts for a status code, return error_$c_get_text(3) 

super-block, update sync(2) 

support, RTE/MPE-style message catalog catread(3C) 

suppress echo while reading password from terminal getpass(3C) 

suspend execution for interval sleep(3C) 

suspend or resume auditing on current process audswitch(2) 

suspend process until signal pause(2) 

svc_destroy() - destroy RPC service transport handle rpc(3C) 

svcerr_auth() -refuse service because of authentication error rpc(3C) 

svcerr_decode ( ) — service cannot decode its parameters rpc(3C) 
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svcerr_noproc ( ) - service hasn't implemented the desired procedure rpc(3C 

svcerr_noprog ( ) - program not registered with RPC package rpc(3C 

svcerr_progvers ( ) - version not registered with RPC package rpc(3C 

svcerr_systemerr ( ) - service detected system error rpc(3C 

svcerr_weakauth() - refuse service due to insufficient authentication rpc(3C 

svcf d_create ( ) - create RPC service from existing socket rpc(3C 

svc_f dset ( ) - global array with RPC service file descriptor mask rpc(3C 

svc_f reeargs ( ) - free data allocated by RPC/XDR rpc(3C 

svc_getargs ( ) - decode arguments in RPC request rpc(3C 

svc_getcaller ( ) - get procedure caller's network address rpc(3C 

svc_getreqset ( ) - return when all associated sockets have been serviced rpc(3C 

svcraw_create ( ) - create toy RPC service transport for testing rpc(3C 

svc_run( ) - wait for RPC requests to arrive and call appropriate service rpc(3C 

svc_sendreply() - send back results of remote procedure call rpc(3C 

svctcp_create ( ) - create RPC service based on TCP transport rpc(3C 

svcudp_create ( ) - create RPC service based on UDP transport rpc(3C 

svc_unregister ( ) - remove mapping of [prognum,versnum] to dispatch routines rpc(3C 

swab ( ) - swap bytes swab(3C 

swap bytes swab(3C 

swap device for interleaved paging/swapping, add a swapon(2^ 

swapon() - add a swap device for interleaved paging/swapping swapon(2 

swapping, file system swapon(2 

swapping/paging, add a swap device for interleaved swapon® 

symbolic link, read value of readlink(2 

symbolic link to a file, make a .symlink(2 

symbol, look up in shared library ,shl_load(3X 

symlink ( ) - make symbolic fink to a file symlink(2 

synchronize a file's in-core state with its state on disk fsync(2 

synchronize a mapped file jnsync(2 

synchronous I/O multiplexing select® 

sync ( ) , lsync ( ) - update super-block sync(2^ 

sysconf - get configurable system variables sysconf(2 

sys_errlist - system error messages perror(3C 

syslogO -write message onto system log file syslog(3C 

sys_nerr - system error messages .perror(3C 

system, boot reboot® 

system calls and events currently being audited, get getevent(2' 

system calls and events to be audited setevent(2 

system calls, BSD-4.2-compatible kill ( ) , sigvec ( ) , and signal ( ) bsdproc(2 

system-calls error indicator .errno® 

system calls, introduction to intro(2 

system clock date and time, get or set gettimeofday(2 

system error messages perror(3C 

system( ) - issue a shell command .system(3S 

system log, control syslog(3C 

system of process' expected paging behavior, advise madvise(2 

system or monitor audio channel gain, get AGetSystemChannelGain(3X 

system or monitor audio channel gain, set ASetSystemChannelGain(3X' 

system resource consumption limit, get or set getrlimit(2 

system variables, get configurable sysconf(2 

system-wide clock, get current value of getclock(3Q 

system-wide clock, set value of .setclock(3C 

table, eliminate duplicate entries in a lsearch(3C 

table, linear search for entry; optional update if missing lsearch(3C 

tables, binary search routine for sorted bsearch(3C 

tables, hash search, manage lisearch(3C 

tandf ( ) - trigonometric tangent function (float, degrees) ...trigd(3lVI 

tand() - trigonometric tangent function (degrees) trigd(3M' 
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tanf ( ) - trigonometric tangent function (float) trig(3M) 

tangent trigonometric function (degrees) trigd(3M) 

tangent trigonometric function .trig(3M) 

tanhf (), tanh() - hyperbolic tangent functions sinh(3M) 

tanh{ ) — inverse hyperbolic tancent function .................. ........................,,,,..,,,,■,.,,,„.... asinh(3M) 

tanh(), tanhf () - hyperbolic tangent functions sinh(3M) 

tan() - trigonometric tangent function trig(3M) 

tcdrain(): tty line control function tccontrol(3C) 

tcf low ( ) : tty line control function tccontrol(3C) 

tcf lush ( ) : tty line control function tccontrol(3C) 

tcgetattr () : get tty device operating parameters ,.„,„„„,„„„„„,,„„„„, tcattribute(3C) 

tcgetpgrp ( ) : get foreground process group ID tcgetpgrp(3C) 

tcsendbreak ( ) : tty line control function tccontrol(3C) 

tcsetattr ( ) : set tty device operating parameters tcattribute(3C) 

tcsetpgrp ( ) : get foreground process group ID tcsetpgrp(3C) 

tdelete ( ) - delete a node from a binary search tree tsearch(3C) 

telldirO - get current location of named directory stream directory(3C) 

tempnam( ) - create a name for a temporary file tmpnam(3S) 

temporary file, create a name for , tmpnam(3S) 

temporary file, create a .tmpfile(3S) 

temporary (unique) file name, make a mktemp(3C) 

termcap ( ) access routines, emulate /etc/ termcap(3X) 

terminal block-mode library interface .blmode(3C) 

terminal, find name of .ttyname(3C) 

terminal, generate file name of controlling ctermid(3S) 

terminal I/O, block-mode library interface for blmode(3C) 

terminal line connection, establish an out-bound dial(3C) 

terminal, read password from while suppressing echo getpass(3C) 

terminate a per-process timer rmtimer(3C) 

terminated, determine how last I/O read io_get_term_reason(3l) 

terminate, wait for child or traced process to stop or wait(2) 

termination character on special file, set up I/O read io_eol_ctl(3l) 

termination, register a function to be called at program atexit(2) 

test contents of memory area jnemory(3C) 

test for INFINITY isinf(3M) 

test for NaN isnan(3M) 

test, initialize, and manipulate signal sets sigsetops(3C) 

text database operations, error error_$intro(3) 

text, data, or process, lock in memory .plock(2) 

text describing NetlPC error number, provide ipcerrmsg(3N) 

texts for a status code, return subsystem, module, and error error_$c_get_text(3) 

tf ind ( ) - get data pointer for binary search tree tsearch(3C) 

tgetent ( ) - get compiled terminfo data base entry into buffer termcap (3X) 

tgetf lag( ) - get availability of compiled boolean terminal capability termcap (3X) 

tgetnumO -get numeric value of compiled terminal capability termcap (3X) 

tgetstrO -get string value of compiled terminal capability termcap(3X) 

tgoto() - get compiled terminal cursor addressing string termcap (3X) 

three-byte integers and long integers, convert between l3tol(3C) 

time and date, convert to string .ctime(3C) 

time and date, convert to string .strftime(3C) 

time and date, convert to wide-character string wcsftime(3C) 

time and date, get more precisely (Version 7 compatibility only) ftime(2) 

time and date, get or set system clock gettimeofday(2) 

time and date, set stime(2) 

time, convert user format date and getdate(3C) 

time, get time(2) 

time ( ) - get time iime(2) 

time limit for I/O operations, set io_timeout_ctl(3l) 
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timeout limit for I/O operations, set io_timeout_ctl(3r 

time profile, execution profil(2 

timer, allocate a per-process jtnktimer(3C 

timer, free a per-process rmtimer(3C 

timer, get value of a per-process .gettimer(3C 

timer, relatively arm a per-process xeltimer(3C 

timer, set or get value of process interval getitimer(2 

times, file access and modification, set or update .......,.,..,....,,,.,„,,,,.....„,„,. utime(2) 

times ( ) - get process and child process times times(2 

times, get process and child process times (2 

time used, report CPU jclock(3C 

timezone ( ) - difference between UCT and local timezone ctime(3C 

tmpf ile ( ) - create a temporary file tmpfile(3S 

tmpnam( ) - create a name for a temporary file tmpnam(3S 

toascii ( ) - translate characters to 7-bit ASCII conv(3C 

tolowerO, _tolower{) -translate characters to lowercase conv(3C 

toolkit, add callback procedure for audio AtAddCallback(3X 

tools to process 16-bit characters nl_tools_16(3C 

toupperO, _toupper(), - translate characters to uppercase conv(3C 

towlower ( ) - translate wide characters to lowercase wconv(3C 

towupperO - translate wide characters to uppercase wconv(3C 

tputs ( ) - decode terminal string padding information termcap(3X 

traced process to stop or terminate, wait for child or wait(2 

trace, process ptrace(2 

transaction channel gain, get AGetChannelGain(3X 

transaction channel gain, set .ASetChannelGain(3X 

transfer speed, inform system of required minimum I/O io_speed_ctl(3l) 

translate character code to another code set iconv(3C 

translate characters for use with NLS (obsolete - useconv(3C)) nl_conv(3C 

translate characters to uppercase, lowercase, or 7-bit ASCII conv(3C 

translate wide characters to uppercase or lowercase wconv(3C 

traverse a binary search tree tsearch(3C 

traverse (walk) a file tree ftw(3C 

tree, manage a binary search .tsearch(3C 

tree, walk a file ftw(3C 

triangle, right, hypotenuse of a Jbypot(3M) 

trigonometric functions (degrees) trigd(3lVl 

trigonometric functions, hyperbolic ^inh(3M 

trigonometric functions, inverse hyperbolic asinh(3M 

trigonometric functions .trig(3M' 

true, wait until the requested status condition becomes hpib_status_wait(3l) 

truncate an existing file to zero for rewriting creat(2^ 

truncate (), ftruncateO - truncate a file to a specified length truncated 

tsearchO -build and access a binary search tree tsearch(3C 

tty baud rate, set or get .cfspeed(3C 

tty device operating parameters, get or set tcattribute(3C 

tty line control functions .tccontrol(3C 

ttynameO, isattyO - find name of a terminal ttyname(3C 

ttyslot ( ) - find the slot in the utmp ( ) file of the current user ttyslot(3C 

twalk ( ) - traverse a binary search tree tsearch(3C 

type, classify characters according to .ctype(3C 

type, classify characters according to .wctype(3C 

type of NLS characters, classify jil_ctype(3C 

tzname ( ) - name of local timezone ctime(3C 

tzset ( ) - initialize timezone ( ) , daylight ( ) , and tzname ( ) using TZ variable ctime(3C 

UID, get name from (obsolete) getpw(3C 

ulimit ( ) - get or set file size limits and break value ulimit(2 

ultoa ( ) ; convert unsigned long integer to ASCII decimal ltostr(3C 
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ultostr ( ) ; convert unsigned long integer to string ltostr(3C) 

umask ( ) - set and get file creation (permissions) mask umask(2) 

umount ( ) - unmount a file system umount(2) 

uname ( ) - get name and version of current HP-UX system uname(2) 

underflow mode (floating-point), examine and set £pgetround(3M) 

undial ( ) , dial ( ) - establish an out-bound terminal line connection dial(3C) 

ungetc ( ) - push character back into input stream ungetc(3S) 

ungetwc ( ) - push wide character back into input stream ungetwc(3C) 

unique (usually temporary) file name, make a mktemp(3C) 

unlink - remove directory entry; delete file unlink (2) 

unload shared library shl_load(3X) 

unlock a semaphore jnsem_unlock(2) 

unlock or lock an I/O interface io_lock(3l) 

unmap a mapped region .munmap(2) 

unmount a file system .umount(2) 

unsigned long integer to string, convert ltostr(3C) 

update a file's header AUpdateDataLength(3X) 

update or set file access and modification times 4 utime(2) 

update super-block sync(2) 

update table if entry missing after search lsearch(3C) 

update user password in Network Information Service yppasswd(3N) 

uppercase, translate characters to conv(3C) 

uppercase, translate wide characters to wconv(3C) 

user, current, find the slot in the utmp ( ) file of the ttyslot(3C) 

user format date and time, convert .getdate(3C) 

user ID, get real or effective getuid(2) 

user ID, set setuid(2) 

user login name, get character-string representation of cuserid(3S) 

user login name, obtain logname(3C) 

user or group IDs, set real, effective, and/or saved ...setresuid(2) 

user password in Network Information Service, update yppasswd(3N) 

user's effective access rights to a file, get a getaccess(2) 

user shells, get legal getusershell(3C) 

users on remote machines, return information about rnusers(3N) 

ustat ( ) - get mounted file system statistics us tat (2) 

utime ( ) - set or update file access and modification times utime(2) 

utmpO file of the current user, find the slot in the ttyslot(3C) 

utmp ( ) , get pointer to login name in getlogin(3C) 

utmpname ( ) - change name of utmp ( ) file being examined getut(3C) 

utmp ( ) or wtmp ( ) file, access getut(3C) 

value, change or add to environment .putenv(3C) 

value, get or set file size limits and break ulimit(2) 

value occurs, wait until a particular parallel poll hpib_wait_onjppoll(3l) 

value of a per-process timer, get gettimer(3C) 

value of process interval timer, set or get getitimer(2) 

value of system-wide clock, get current getclock(3C) 

value of system-wide clock, set .setclock(3C) 

value, return integer absolute nbs(3C) 

values, convert between host and network byte order byteorder(3N) 

values, get string-valued configuration confstr(3C) 

varargs argument, formatted input conversion to a vscanf(3S) 

varargs argument list, print formatted output of a vprintf(3S) 

variable, environment, search environment list for value of getenv(3C) 

variables, configurable pathname, get .pathconf(2) 

variables, system, get configurable sysconf(2) 

VC socket, determine status of ipcselect(2) 

vector, get option letter from argument getopt(3C) 

verify program assertion assert(3X) 
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version and name of current HP-UX system, get uname(2) 

vf ork ( ) - spawn new process (use fork ( ) instead) vfork(2) 

vfprintf ( ) - print formatted output of a varargs argument list vprintf(3S) 

vfscanf ( ) - formatted input conversion to a varargs argument vscanf(3S) 

vf amount ( ) - mount a file system .vfsmount(2) 

virtual circuit connection, establish or receive data on NetlPC ipcrecv(2) 

virtual circuit connection, send data on a ipcsend(2) 

Virtual Circuit socket, determine status of ipcselect(2) 

virtual memory, map object into jnmap(2) 

vprintf ( ) , vfprintf ( ) , vsprintf ( ) - print formatted output of a varargs argument list vprintf(3S) 

vscanf ( ) - formatted input conversion to a varargs argument vscanf(3S) 

vsprintf ( ) - print formatted output of a varargs argument list vprintf(3S) 

vsscanf ( ) - formatted input conversion to a varargs argument vscanf(3S) 

wait for a signal sigsuspend(2) 

wait for interrupt, atomically release blocked signals and sigpause(2) 

wait until a particular parallel poll value occurs hpib_wait_onj>poll(3l) 

wait until the requested status condition becomes true hpib_status_wait(3l) 

wait (), waitpidO, wait 3 () -wait for child or traced process to stop or terminate wait(2) 

walk a file tree ftw(3C) 

wcharadvo, - put character in memory and advance pointer nl_tools_16(3C) 

wcHAR(),-put8-or 16-bit character in memory nl_tools_16(3C) 

wcscat, wcsncat - append wide string 2 to wide string 1 wcstring(3C) 

wcschr, wcsrchr-get pointer to wide character in wide string wcstring(3C) 

wcscmp, wcsncmp - compare two wide strings wcstring(3C) 

wcscoll - process wide string of text tokens wcstring(3C) 

wcscpy, wcsncpy- copy wide string 2 to wide string 1 wcstring(3C) 

wcscspn, wcsspn - find length of matching wide substrings wcstring(3C) 

wcsf time ( ) - convert date and time to wide-character string wcsftime(3C) 

wcslen- determine length of a wide string wcstring(3C) 

wcspbrk - find occurrence of wide character from wide string 2 in wide string 1 wcstring(3C) 

wcstod( ) - convert wide character string to double-precision number wcstod(3C) 

wcstok - process wide string of text tokens wcstring(3C) 

wcstolO - convert wide character string to long integer wcstol(3C) 

wcstombs ( ) - multibyte characters and strings conversions multibyte(3C) 

wcswcs - process wide string of text tokens wcstring(3C) 

wctomb( ) - multibyte characters and strings conversions multibyte(3C) 

wide character back into input stream, push ungetwc(3C) 

wide character from a stream file, get getwc(3C) 

wide character, put on a stream putwc(3C) 

wide characters, translate to uppercase or lowercase wconv(3C) 

wide-character string, convert date and time to wcsftime(3C) 

wide character string operations .wcstring(3C) 

wide character string to double-precision number, convert wcstod(3C) 

wide character string to long integer, convert wcstol(3C) 

wide string from a standard input stream, input getws(3C) 

wide strings, concatenate two .wcstring(3C) 

widget, audio play AuPlayWidget(3X) 

widget, audio record AuRecordWidget(3X) 

widget, create an audio play AuCreatePlay(3X) 

widget, create an audio record AuCreateRecord(3X) 

widget play operation, initiate an audio AuInvokePlay(3X) 

widget record operation, initiate an audio AuInvokeRecord(3X) 

widget, save sound bucket data created by record AuSaveFile(3X) 

width (in bits) of data path, set io_width_ctl(3l) 

word expansions, perform .wordexp(3C) 

wordexp - perform word expansions wordexp(3C) 

wordf ree - perform word expansions wordexp(3C) 

word from a stream file, get character or data getc(3S) 
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word or character, put on a stream .putc(3S) 

working directory, change jchdir(2) 

working directory, get path-name of current getcwd(3C) 

write a header for an audio file AWriteAHeader(3X) 

write a null-terminated string on a stream puts(3S) 

write a null-terminated wide string on a stream fputws(3C) 

write audit record for self-auditing process audwrite(2) 

write password file entry .putpwent(3C) 

write/read file pointer, move lseek(2) 

write secure password file entry putspwent(3C) 

write sound bucket data into file with data conversion ASaveSBucket(SX) 

write to specified remote machines jrwall(3N) 

writev ( ) - write non-contiguous data to a file write(2) 

write ( ) - write contiguous data to a file write(2) 

writing or reading, open file for .open(2) 

wtmp ( ) or utmp ( ) file, access .getut(3C) 

xdr() : library routines for external data representation xdr(3C) 

xdr_accepted_reply ( ) -generate RPC-style replies without using RPC package rpc(3C) 

xdr_array() -translate arrays to/from external representation xdr(3C) 

xdr_authunix_parms ( ) - generate UNIX credentials without using RPC package rpc(3C) 

xdr_bool() - translate Booleans to/from external representation xdr(3C) 

xdr_bytes ( ) - translate counted byte strings to/from external representation xdr(3C) 

xdr_callhdr() - generate RPC-style headers without using RPC package rpc(3C) 

xdr_callmsg ( ) - generate RPC-style messages without using RPC package rpc(3C) 

xdr_char ( ) - translate characters to/from external representation xdr(3C) 

xdr_destroy() - destroy XDR stream and free associated memory xdr(3C) 

xdr_double ( ) - translate double precision to/from external representation xdr(3C) 

xdr_enum() - translate enumerations to/from external representation xdr(3C) 

xdr_f loat ( ) - translate floating point to/from external representation xdr(3C) 

xdr_f ree ( ) - free the memory allocated to create XDR data structures xdr(3C) 

xdr_getpos() - return current position in XDR stream xdr(3C) 

xdr_inline ( ) - invoke the in-line routines associated with XDR stream xdr(3C) 

xdr_int ( ) - translate integers to/from external representation xdr(3C) 

xdr_long () - translate long integers to/from external representation xdr(3C) 

xdrmem_create ( ) - initialize an XDR stream xdr(3C) 

xdr_opaque_auth ( ) - describe RPC messages externally rpc(3C) 

xdr_opaque ( ) - translate fixed-size opaque data to/from external representation xdr(3C) 

xdr_pmap() - describe parameters for portmap procedures externally rpc(3C) 

xdr_pmaplist ( ) - describe a list of port mappings externally rpc(3C) 

xdr_pointer ( ) - similar to xdr_ref erence ( ) but different xdr(3C) 

xdrrec_create ( ) - initialize an XDR stream with record boundaries xdr(3C) 

xdrrec_endofrecord() - mark XDR record stream with an end-of-record xdr(3C) 

xdrrec_eof ( ) - mark XDR record stream with an end-of-file xdr(3C) 

xdrrec_skiprecord ( ) - skip remaining record in XDR record stream xdr(3C) 

xdr_ref erence ( ) - chase pointers within structures xdr(3C) 

xdr_re j ected_reply ( ) - generate RPC-style rejections without using RPC package rpc(3C) 

xdr_replymsg ( ) - generate RPC-style replies without using RPC package rpc(3C) 

xdr_setpos() - change current position in XDR stream xdr(3C) 

xdr_short ( ) - translate short integers to/from external representation xdr(3C) 

xdrstdio_create ( ) - initialize XDR stream as standard I/O FILE stream xdr(3C) 

xdr_string ( ) - translate null-terminated strings to/from external representation xdr(3C) 

xdr_u_ch.ar ( ) - translate unsigned characters to/from external representation xdr(3C) 

xdr_u_int ( ) - translate unsigned integers to/from external representation xdr(3C) 

xdr_u_long ( ) - translate unsigned long integers to/from external representation xdr(3C) 

xdr_union() -translate descriminated unions to/from external representation xdr(3C) 

xdr_u_sh.ort ( ) - translate unsigned short integers to/from external representation xdr(3C) 

xdr_vector ( ) - translate fixed-length arrays to/from external representation xdr(3C) 

xdr_void() - always return one (1) xdr(3C) 
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